From fb5a4bac6e4680a5174a6c95c1792ea13c17643b Mon Sep 17 00:00:00 2001 From: Haoyu Qiu <timothyqiu32@gmail.com> Date: Mon, 25 Nov 2024 22:35:01 +0800 Subject: Improve documentation for tooltip-related methods --- doc/classes/Control.xml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index d22be4a52d..2cf2bdf056 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -113,7 +113,7 @@ <param index="0" name="at_position" type="Vector2" /> <description> Virtual method to be implemented by the user. Returns the tooltip text for the position [param at_position] in control's local coordinates, which will typically appear when the cursor is resting over this control. See [method get_tooltip]. - [b]Note:[/b] If this method returns an empty [String], no tooltip is displayed. + [b]Note:[/b] If this method returns an empty [String] and [method _make_custom_tooltip] is not overridden, no tooltip is displayed. </description> </method> <method name="_gui_input" qualifiers="virtual"> @@ -164,11 +164,12 @@ <return type="Object" /> <param index="0" name="for_text" type="String" /> <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. The [param for_text] includes the contents of the [member tooltip_text] property. + Virtual method to be implemented by the user. Returns a [Control] node that should be used as a tooltip instead of the default one. [param for_text] is the return value of [method get_tooltip]. 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 tooltip_text] 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 custom_minimum_size] to some non-zero value. [b]Note:[/b] The node (and any relevant children) should have their [member CanvasItem.visible] set to [code]true[/code] when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably. + [b]Note:[/b] If overridden, this method is called even if [method get_tooltip] returns an empty string. When this happens with the default tooltip, it is not displayed. To copy this behavior, return [code]null[/code] in this method when [param for_text] is empty. [b]Example:[/b] Use a constructed node as a tooltip: [codeblocks] [gdscript] @@ -553,7 +554,7 @@ <description> Returns the tooltip text for the position [param at_position] in control's local coordinates, which will typically appear when the cursor is resting over this control. By default, it returns [member tooltip_text]. This method can be overridden to customize its behavior. See [method _get_tooltip]. - [b]Note:[/b] If this method returns an empty [String], no tooltip is displayed. + [b]Note:[/b] If this method returns an empty [String] and [method _make_custom_tooltip] is not overridden, no tooltip is displayed. </description> </method> <method name="grab_click_focus"> @@ -1065,7 +1066,8 @@ [b]Note:[/b] Tooltips customized using [method _make_custom_tooltip] do not use this auto translate mode automatically. </member> <member name="tooltip_text" type="String" setter="set_tooltip_text" getter="get_tooltip_text" default=""""> - The default 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]. The time required for the tooltip to appear can be changed with the [member ProjectSettings.gui/timers/tooltip_delay_sec] option. See also [method get_tooltip]. + The default 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]. The time required for the tooltip to appear can be changed with the [member ProjectSettings.gui/timers/tooltip_delay_sec] setting. + This string is the default return value of [method get_tooltip]. Override [method _get_tooltip] to generate tooltip text dynamically. Override [method _make_custom_tooltip] to customize the tooltip interface and behavior. 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] -- cgit v1.2.3