nick/godot
1
0
Fork 0
mirror of https://github.com/godotengine/godot.git synced 2026-03-03 20:55:48 +00:00
Code Issues 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.
This commit is contained in:
Rémi Verschelde
2020-11-02 17:18:29 +01:00
parent 873d461785
commit c5d8dafec4
4 changed files with 81 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
doc/classes/Control.xml
View File

@@ -75,15 +75,17 @@
</description>
</method>
<method name="_make_custom_tooltip" qualifiers="virtual">
<return type="Object">
<return type="Control">
</return>
<argument index="0" name="for_text" type="String">
</argument>
<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]).
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.
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-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.
Example of usage with custom-constructed node:
[b]Note:[/b] The node (and any relevant children) should be [member CanvasItem.visible] when returned, otherwise the viewport that instantiates it will not be able to calculate its minimum size reliably.
Example of usage with a custom-constructed node:
[codeblocks]
[gdscript]
func _make_custom_tooltip(for_text):
@@ -92,7 +94,7 @@
return label
[/gdscript]
[csharp]
public override Godot.Object _MakeCustomTooltip(String forText)
public override Godot.Control _MakeCustomTooltip(String forText)
{
var label = new Label();
label.Text = forText;
@@ -100,18 +102,18 @@
}
[/csharp]
[/codeblocks]
Example of usage with custom scene instance:
Example of usage with a custom scene instance:
[codeblocks]
[gdscript]
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
return tooltip
[/gdscript]
[csharp]
public override Godot.Object _MakeCustomTooltip(String forText)
public override Godot.Control _MakeCustomTooltip(String forText)
{
Node tooltip = ResourceLoader.Load&lt;PackedScene&gt;("SomeTooltipScene.tscn").Instance();
Node tooltip = ResourceLoader.Load&lt;PackedScene&gt;("res://SomeTooltipScene.tscn").Instance();
tooltip.GetNode&lt;Label&gt;("Label").Text = forText;
return tooltip;
}
@@ -993,6 +995,25 @@
</member>
<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.
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:
[codeblocks]
[gdscript]
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))
[/gdscript]
[csharp]
var styleBox = new StyleBoxFlat();
styleBox.SetBgColor(new Color(1, 1, 0));
styleBox.SetBorderWidthAll(2);
// We assume here that the `Theme` property has been assigned a custom Theme beforehand.
Theme.SetStyleBox("panel", "TooltipPanel", styleBox);
Theme.SetColor("font_color", "TooltipLabel", new Color(0, 1, 1));
[/csharp]
[/codeblocks]
</member>
<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].