From c5d8dafec4c57d05e97bdce06b2e43bdcc6846bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Mon, 2 Nov 2020 17:18:29 +0100 Subject: Tooltips: Improve code clarity and docs 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. --- doc/classes/Control.xml | 39 ++++++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 9 deletions(-) (limited to 'doc/classes') diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index f495bfe894..6ea7b79dff 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -75,15 +75,17 @@ - + - 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<PackedScene>("SomeTooltipScene.tscn").Instance(); + Node tooltip = ResourceLoader.Load<PackedScene>("res://SomeTooltipScene.tscn").Instance(); tooltip.GetNode<Label>("Label").Text = forText; return tooltip; } @@ -993,6 +995,25 @@ 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] Distance between the node's bottom edge and its parent control, based on [member anchor_bottom]. -- cgit v1.2.3