godotengine/godot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Tooltips: Improve code clarity and docs

Browse Source 
The return type for `_make_custom_tooltip` is clarified as Control, and users
should make sure to return a visible node for proper size calculations.

Moreover in the current master branch, a PopupPanel will be added as parent
to the provided tooltip to make it a sub-window.

Clarifies documentation for `Control._make_custom_tooltip`, and shows how to
use the (until now undocumented) "TooltipPanel" and "TooltipLabel" theme types
to style tooltips.

Fixes #39677.

(cherry picked from commit c5d8dafec4)
This commit is contained in:
Rémi Verschelde 2020-11-02 17:18:29 +01:00
parent de96b29c58
commit 05143ca39a
No known key found for this signature in database
GPG Key ID: C3336907360768E1
4 changed files with 72 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/classes/Control.xml
View File

@ -58,25 +58,26 @@
</description> </description>
</method> </method>
<method name="_make_custom_tooltip" qualifiers="virtual"> <method name="_make_custom_tooltip" qualifiers="virtual">
<return type="Object"> <return type="Control">
</return> </return>
<argument index="0" name="for_text" type="String"> <argument index="0" name="for_text" type="String">
</argument> </argument>
<description> <description>
Virtual method to be implemented by the user. Returns a [Control] node that should be used as a tooltip instead of the default one. Use [code]for_text[/code] parameter to determine what text the tooltip should contain (likely the contents of [member hint_tooltip]). Virtual method to be implemented by the user. Returns a [Control] node that should be used as a tooltip instead of the default one. The [code]for_text[/code] includes the contents of the [member hint_tooltip] property.
The returned node must be of type [Control] or Control-derieved. It can have child nodes of any type. It is freed when the tooltip disappears, so make sure you always provide a new instance, not e.g. a node from scene. When [code]null[/code] or non-Control node is returned, the default tooltip will be used instead. The returned node must be of type [Control] or Control-derived. It can have child nodes of any type. It is freed when the tooltip disappears, so make sure you always provide a new instance (if you want to use a pre-existing node from your scene tree, you can duplicate it and pass the duplicated instance).When [code]null[/code] or a non-Control node is returned, the default tooltip will be used instead.
The returned node will be added as child to a [PopupPanel], so you should only provide the contents of that panel. That [PopupPanel] can be themed using [method Theme.set_stylebox] for the type [code]"TooltipPanel"[/code] (see [member hint_tooltip] for an example).
[b]Note:[/b] The tooltip is shrunk to minimal size. If you want to ensure it's fully visible, you might want to set its [member rect_min_size] to some non-zero value. [b]Note:[/b] The tooltip is shrunk to minimal size. If you want to ensure it's fully visible, you might want to set its [member rect_min_size] to some non-zero value.
Example of usage with custom-constructed node: Example of usage with a custom-constructed node:
[codeblock] [codeblock]
func _make_custom_tooltip(for_text): func _make_custom_tooltip(for_text):
var label = Label.new() var label = Label.new()
label.text = for_text label.text = for_text
return label return label
[/codeblock] [/codeblock]
Example of usage with custom scene instance: Example of usage with a custom scene instance:
[codeblock] [codeblock]
func _make_custom_tooltip(for_text): func _make_custom_tooltip(for_text):
var tooltip = preload("SomeTooltipScene.tscn").instance() var tooltip = preload("res://SomeTooltipScene.tscn").instance()
tooltip.get_node("Label").text = for_text tooltip.get_node("Label").text = for_text
return tooltip return tooltip
[/codeblock] [/codeblock]
@ -846,6 +847,15 @@
</member> </member>
<member name="hint_tooltip" type="String" setter="set_tooltip" getter="_get_tooltip" default="&quot;&quot;"> <member name="hint_tooltip" type="String" setter="set_tooltip" getter="_get_tooltip" default="&quot;&quot;">
Changes the tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the [member mouse_filter] property is not [constant MOUSE_FILTER_IGNORE]. You can change the time required for the tooltip to appear with [code]gui/timers/tooltip_delay_sec[/code] option in Project Settings. Changes the tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the [member mouse_filter] property is not [constant MOUSE_FILTER_IGNORE]. You can change the time required for the tooltip to appear with [code]gui/timers/tooltip_delay_sec[/code] option in Project Settings.
The tooltip popup will use either a default implementation, or a custom one that you can provide by overriding [method _make_custom_tooltip]. The default tooltip includes a [PopupPanel] and [Label] whose theme properties can be customized using [Theme] methods with the [code]"TooltipPanel"[/code] and [code]"TooltipLabel"[/code] respectively. For example:
[codeblock]
var style_box = StyleBoxFlat.new()
style_box.set_bg_color(Color(1, 1, 0))
style_box.set_border_width_all(2)
# We assume here that the `theme` property has been assigned a custom Theme beforehand.
theme.set_stylebox("panel", "TooltipPanel", style_box)
theme.set_color("font_color", "TooltipLabel", Color(0, 1, 1))
[/codeblock]
</member> </member>
<member name="margin_bottom" type="float" setter="set_margin" getter="get_margin" default="0.0"> <member name="margin_bottom" type="float" setter="set_margin" getter="get_margin" default="0.0">
Distance between the node's bottom edge and its parent control, based on [member anchor_bottom]. Distance between the node's bottom edge and its parent control, based on [member anchor_bottom].

4
scene/gui/control.cpp
View File

@ -2960,7 +2960,9 @@ void Control::_bind_methods() {
BIND_VMETHOD(MethodInfo(Variant::BOOL, "can_drop_data", PropertyInfo(Variant::VECTOR2, "position"), PropertyInfo(Variant::NIL, "data"))); BIND_VMETHOD(MethodInfo(Variant::BOOL, "can_drop_data", PropertyInfo(Variant::VECTOR2, "position"), PropertyInfo(Variant::NIL, "data")));
BIND_VMETHOD(MethodInfo("drop_data", PropertyInfo(Variant::VECTOR2, "position"), PropertyInfo(Variant::NIL, "data"))); BIND_VMETHOD(MethodInfo("drop_data", PropertyInfo(Variant::VECTOR2, "position"), PropertyInfo(Variant::NIL, "data")));
BIND_VMETHOD(MethodInfo(Variant::OBJECT, "_make_custom_tooltip", PropertyInfo(Variant::STRING, "for_text"))); BIND_VMETHOD(MethodInfo(
PropertyInfo(Variant::OBJECT, "control", PROPERTY_HINT_RESOURCE_TYPE, "Control"),
"_make_custom_tooltip", PropertyInfo(Variant::STRING, "for_text")));
BIND_VMETHOD(MethodInfo(Variant::BOOL, "_clips_input")); BIND_VMETHOD(MethodInfo(Variant::BOOL, "_clips_input"));
ADD_GROUP("Anchor", "anchor_"); ADD_GROUP("Anchor", "anchor_");

98
scene/main/viewport.cpp
View File

@ -169,6 +169,11 @@ ViewportTexture::~ViewportTexture() {
///////////////////////////////////// /////////////////////////////////////
// Aliases used to provide custom styles to tooltips in the default
// theme and editor theme.
// TooltipPanel is also used for custom tooltips, while TooltipLabel
// is only relevant for default tooltips.
class TooltipPanel : public PanelContainer { class TooltipPanel : public PanelContainer {
GDCLASS(TooltipPanel, PanelContainer); GDCLASS(TooltipPanel, PanelContainer);
@ -185,6 +190,8 @@ public:
TooltipLabel(){}; TooltipLabel(){};
}; };
/////////////////////////////////////
Viewport::GUI::GUI() { Viewport::GUI::GUI() {
dragging = false; dragging = false;
@ -194,7 +201,7 @@ Viewport::GUI::GUI() {
key_focus = NULL; key_focus = NULL;
mouse_over = NULL; mouse_over = NULL;
tooltip = NULL; tooltip_control = NULL;
tooltip_popup = NULL; tooltip_popup = NULL;
tooltip_label = NULL; tooltip_label = NULL;
subwindow_visibility_dirty = false; subwindow_visibility_dirty = false;
@ -1528,7 +1535,7 @@ void Viewport::_gui_sort_roots() {
void Viewport::_gui_cancel_tooltip() { void Viewport::_gui_cancel_tooltip() {
gui.tooltip = NULL; gui.tooltip_control = NULL;
gui.tooltip_timer = -1; gui.tooltip_timer = -1;
if (gui.tooltip_popup) { if (gui.tooltip_popup) {
gui.tooltip_popup->queue_delete(); gui.tooltip_popup->queue_delete();
@ -1537,7 +1544,7 @@ void Viewport::_gui_cancel_tooltip() {
} }
} }
String Viewport::_gui_get_tooltip(Control *p_control, const Vector2 &p_pos, Control **r_which) { String Viewport::_gui_get_tooltip(Control *p_control, const Vector2 &p_pos, Control **r_tooltip_owner) {
Vector2 pos = p_pos; Vector2 pos = p_pos;
String tooltip; String tooltip;
@ -1546,19 +1553,25 @@ String Viewport::_gui_get_tooltip(Control *p_control, const Vector2 &p_pos, Cont
tooltip = p_control->get_tooltip(pos); tooltip = p_control->get_tooltip(pos);
if (r_which) { if (r_tooltip_owner) {
*r_which = p_control; *r_tooltip_owner = p_control;
} }
if (tooltip != String()) // If we found a tooltip, we stop here.
if (!tooltip.empty()) {
break; break;
pos = p_control->get_transform().xform(pos); }
// Otherwise, we check parent controls unless some conditions prevent it.
if (p_control->data.mouse_filter == Control::MOUSE_FILTER_STOP) if (p_control->data.mouse_filter == Control::MOUSE_FILTER_STOP)
break; break;
if (p_control->is_set_as_toplevel()) if (p_control->is_set_as_toplevel())
break; break;
// Transform cursor pos for parent control.
pos = p_control->get_transform().xform(pos);
p_control = p_control->get_parent_control(); p_control = p_control->get_parent_control();
} }
@ -1567,33 +1580,39 @@ String Viewport::_gui_get_tooltip(Control *p_control, const Vector2 &p_pos, Cont
void Viewport::_gui_show_tooltip() { void Viewport::_gui_show_tooltip() {
if (!gui.tooltip) { if (!gui.tooltip_control) {
return; return;
} }
Control *which = NULL; // Get the Control under cursor and the relevant tooltip text, if any.
String tooltip = _gui_get_tooltip(gui.tooltip, gui.tooltip->get_global_transform().xform_inv(gui.tooltip_pos), &which); Control *tooltip_owner = NULL;
tooltip = tooltip.strip_edges(); String tooltip_text = _gui_get_tooltip(
if (tooltip.length() == 0) gui.tooltip_control,
return; // bye gui.tooltip_control->get_global_transform().xform_inv(gui.tooltip_pos),
&tooltip_owner);
tooltip_text.strip_edges();
if (tooltip_text.empty()) {
return; // Nothing to show.
}
// Remove previous popup if we change something.
if (gui.tooltip_popup) { if (gui.tooltip_popup) {
memdelete(gui.tooltip_popup); memdelete(gui.tooltip_popup);
gui.tooltip_popup = NULL; gui.tooltip_popup = NULL;
gui.tooltip_label = NULL; gui.tooltip_label = NULL;
} }
if (!which) { if (!tooltip_owner) {
return; return;
} }
Control *rp = which; // Controls can implement `make_custom_tooltip` to provide their own tooltip.
// This should be a Control node which will be added as child to the tooltip owner.
gui.tooltip_popup = which->make_custom_tooltip(tooltip); gui.tooltip_popup = tooltip_owner->make_custom_tooltip(tooltip_text);
// If no custom tooltip is given, use a default implementation.
if (!gui.tooltip_popup) { if (!gui.tooltip_popup) {
gui.tooltip_popup = memnew(TooltipPanel); gui.tooltip_popup = memnew(TooltipPanel);
gui.tooltip_label = memnew(TooltipLabel); gui.tooltip_label = memnew(TooltipLabel);
gui.tooltip_popup->add_child(gui.tooltip_label); gui.tooltip_popup->add_child(gui.tooltip_label);
@ -1603,14 +1622,14 @@ void Viewport::_gui_show_tooltip() {
gui.tooltip_label->set_anchor_and_margin(MARGIN_TOP, Control::ANCHOR_BEGIN, ttp->get_margin(MARGIN_TOP)); gui.tooltip_label->set_anchor_and_margin(MARGIN_TOP, Control::ANCHOR_BEGIN, ttp->get_margin(MARGIN_TOP));
gui.tooltip_label->set_anchor_and_margin(MARGIN_RIGHT, Control::ANCHOR_END, -ttp->get_margin(MARGIN_RIGHT)); gui.tooltip_label->set_anchor_and_margin(MARGIN_RIGHT, Control::ANCHOR_END, -ttp->get_margin(MARGIN_RIGHT));
gui.tooltip_label->set_anchor_and_margin(MARGIN_BOTTOM, Control::ANCHOR_END, -ttp->get_margin(MARGIN_BOTTOM)); gui.tooltip_label->set_anchor_and_margin(MARGIN_BOTTOM, Control::ANCHOR_END, -ttp->get_margin(MARGIN_BOTTOM));
gui.tooltip_label->set_text(tooltip); gui.tooltip_label->set_text(tooltip_text);
} }
rp->add_child(gui.tooltip_popup); tooltip_owner->add_child(gui.tooltip_popup);
gui.tooltip_popup->force_parent_owned(); gui.tooltip_popup->force_parent_owned();
gui.tooltip_popup->set_as_toplevel(true); gui.tooltip_popup->set_as_toplevel(true);
if (gui.tooltip) // Avoids crash when rapidly switching controls. if (gui.tooltip_control) // Avoids crash when rapidly switching controls.
gui.tooltip_popup->set_scale(gui.tooltip->get_global_transform().get_scale()); gui.tooltip_popup->set_scale(gui.tooltip_control->get_global_transform().get_scale());
Point2 tooltip_offset = ProjectSettings::get_singleton()->get("display/mouse_cursor/tooltip_position_offset"); Point2 tooltip_offset = ProjectSettings::get_singleton()->get("display/mouse_cursor/tooltip_position_offset");
Rect2 r(gui.tooltip_pos + tooltip_offset, gui.tooltip_popup->get_minimum_size()); Rect2 r(gui.tooltip_pos + tooltip_offset, gui.tooltip_popup->get_minimum_size());
@ -1860,7 +1879,7 @@ void Viewport::_gui_input_event(Ref<InputEvent> p_event) {
gui.key_event_accepted = false; gui.key_event_accepted = false;
Control *over = nullptr; Control *over = NULL;
Point2 mpos = mb->get_position(); Point2 mpos = mb->get_position();
if (mb->is_pressed()) { if (mb->is_pressed()) {
@ -2002,8 +2021,6 @@ void Viewport::_gui_input_event(Ref<InputEvent> p_event) {
} }
_gui_cancel_tooltip(); _gui_cancel_tooltip();
//gui.tooltip_popup->hide();
} else { } else {
if (gui.drag_data.get_type() != Variant::NIL && mb->get_button_index() == BUTTON_LEFT) { if (gui.drag_data.get_type() != Variant::NIL && mb->get_button_index() == BUTTON_LEFT) {
@ -2242,8 +2259,8 @@ void Viewport::_gui_input_event(Ref<InputEvent> p_event) {
bool is_tooltip_shown = false; bool is_tooltip_shown = false;
if (gui.tooltip_popup) { if (gui.tooltip_popup) {
if (can_tooltip && gui.tooltip) { if (can_tooltip && gui.tooltip_control) {
String tooltip = _gui_get_tooltip(over, gui.tooltip->get_global_transform().xform_inv(mpos)); String tooltip = _gui_get_tooltip(over, gui.tooltip_control->get_global_transform().xform_inv(mpos));
if (tooltip.length() == 0) if (tooltip.length() == 0)
_gui_cancel_tooltip(); _gui_cancel_tooltip();
@ -2260,14 +2277,12 @@ void Viewport::_gui_input_event(Ref<InputEvent> p_event) {
if (can_tooltip && !is_tooltip_shown) { if (can_tooltip && !is_tooltip_shown) {
gui.tooltip = over; gui.tooltip_control = over;
gui.tooltip_pos = mpos; //(parent_xform * get_transform()).affine_inverse().xform(pos); gui.tooltip_pos = mpos;
gui.tooltip_timer = gui.tooltip_delay; gui.tooltip_timer = gui.tooltip_delay;
} }
} }
//pos = gui.focus_inv_xform.xform(pos);
mm->set_position(pos); mm->set_position(pos);
Control::CursorShape cursor_shape = Control::CURSOR_ARROW; Control::CursorShape cursor_shape = Control::CURSOR_ARROW;
@ -2633,21 +2648,11 @@ void Viewport::_gui_hid_control(Control *p_control) {
_drop_mouse_focus(); _drop_mouse_focus();
} }
/* ???
if (data.window==p_control) {
window->drag_data=Variant();
if (window->drag_preview) {
memdelete( window->drag_preview);
window->drag_preview=NULL;
}
}
*/
if (gui.key_focus == p_control) if (gui.key_focus == p_control)
_gui_remove_focus(); _gui_remove_focus();
if (gui.mouse_over == p_control) if (gui.mouse_over == p_control)
gui.mouse_over = NULL; gui.mouse_over = NULL;
if (gui.tooltip == p_control) if (gui.tooltip_control == p_control)
_gui_cancel_tooltip(); _gui_cancel_tooltip();
} }
@ -2664,8 +2669,8 @@ void Viewport::_gui_remove_control(Control *p_control) {
gui.key_focus = NULL; gui.key_focus = NULL;
if (gui.mouse_over == p_control) if (gui.mouse_over == p_control)
gui.mouse_over = NULL; gui.mouse_over = NULL;
if (gui.tooltip == p_control) if (gui.tooltip_control == p_control)
gui.tooltip = NULL; gui.tooltip_control = NULL;
if (gui.tooltip_popup == p_control) { if (gui.tooltip_popup == p_control) {
_gui_cancel_tooltip(); _gui_cancel_tooltip();
} }
@ -3448,14 +3453,13 @@ Viewport::Viewport() {
disable_3d = false; disable_3d = false;
keep_3d_linear = false; keep_3d_linear = false;
//window tooltip // Window tooltip.
gui.tooltip_timer = -1; gui.tooltip_timer = -1;
//gui.tooltip_timer->force_parent_owned();
gui.tooltip_delay = GLOBAL_DEF("gui/timers/tooltip_delay_sec", 0.5); gui.tooltip_delay = GLOBAL_DEF("gui/timers/tooltip_delay_sec", 0.5);
ProjectSettings::get_singleton()->set_custom_property_info("gui/timers/tooltip_delay_sec", PropertyInfo(Variant::REAL, "gui/timers/tooltip_delay_sec", PROPERTY_HINT_RANGE, "0,5,0.01,or_greater")); // No negative numbers ProjectSettings::get_singleton()->set_custom_property_info("gui/timers/tooltip_delay_sec", PropertyInfo(Variant::REAL, "gui/timers/tooltip_delay_sec", PROPERTY_HINT_RANGE, "0,5,0.01,or_greater")); // No negative numbers
gui.tooltip = NULL; gui.tooltip_control = NULL;
gui.tooltip_label = NULL; gui.tooltip_label = NULL;
gui.drag_preview = NULL; gui.drag_preview = NULL;
gui.drag_attempted = false; gui.drag_attempted = false;

4
scene/main/viewport.h
View File

@ -299,7 +299,7 @@ private:
int mouse_focus_mask; int mouse_focus_mask;
Control *key_focus; Control *key_focus;
Control *mouse_over; Control *mouse_over;
Control *tooltip; Control *tooltip_control;
Control *tooltip_popup; Control *tooltip_popup;
Label *tooltip_label; Label *tooltip_label;
Point2 tooltip_pos; Point2 tooltip_pos;
@ -360,7 +360,7 @@ private:
void _gui_remove_root_control(List<Control *>::Element *RI); void _gui_remove_root_control(List<Control *>::Element *RI);
void _gui_remove_subwindow_control(List<Control *>::Element *SI); void _gui_remove_subwindow_control(List<Control *>::Element *SI);
String _gui_get_tooltip(Control *p_control, const Vector2 &p_pos, Control **r_which = NULL); String _gui_get_tooltip(Control *p_control, const Vector2 &p_pos, Control **r_tooltip_owner = NULL);
void _gui_cancel_tooltip(); void _gui_cancel_tooltip();
void _gui_show_tooltip(); void _gui_show_tooltip();