Tooltips: Improve code clarity and docs #43280

akien-mga · 2020-11-02T19:15:04Z

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.

Supersedes #43273.

My aim initially was to re-add flexibility to Control._make_custom_tooltip in what kind of tooltip popup will be created. In 3.2 you can pass any Control to be used as is, while in master popups derive Window, and thus the custom tooltip Control created by the user is wrapped in a TooltipPanel of type PopupPanel.

I thought some users might want more flexibility here, so I tried to make TooltipPanel part of the public API, and make it so it's no longer used by default in Viewport but should be returned by users in _make_custom_tooltip, if they want it (otherwise they could use another Window-derived control for a popup window, or even another type of Control for some in-game tooltip hints). But since Popup/PopupPanel now inherit Window, they're no longer Control so we have a type mismatch. In the end, I'm not sure the flexibility I was pursuing really corresponds to actual use cases that users have (it came from my own use case in https://github.com/akien-mga/godot-debug-watermark, but I think I can work with styling TooltipPanel as documented in this PR), so I prefer to wait for user feedback before exploring a potentially more flexible API.

akien-mga · 2020-11-02T19:15:54Z

CC @rxlecky as this is partly based on our discussion on #39677.

akien-mga · 2020-11-02T19:17:21Z

doc/classes/Control.xml

+			[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]


I haven't tested my C# conversion yet. If anyone wants to give it a try and confirm that it works, that'd be welcome.

Note that you have to have a valid Theme, which can presumably be created with:

Theme = new Theme(); Theme.CopyDefaultTheme();

rxlecky · 2020-11-02T21:24:06Z

scene/main/viewport.cpp

-	tooltip = tooltip.strip_edges();
-	if (tooltip.length() == 0) {
-		return; // bye
+	String tooltip_text = _gui_get_tooltip(


Very nice clean up on this one, especially the confusing variable names. I wasn't sure when tooltip refers to the control and when to the string when I was looking at that code. Since you are making changes to that function, I'd also rename the which variable to something more descriptive. Perhaps tooltip_text_source? Or tooltip_text_source_node, since tooltip_text_source_control would be a bit confusing, haha.

I thought about renaming which but since it's only used in local code (and a helper method) I didn't feel it was so problematic. But here goes, I renamed it to tooltip_owner.

rxlecky · 2020-11-02T21:26:54Z

scene/main/viewport.cpp

-	Control *base_tooltip = which->make_custom_tooltip(tooltip);
+	// Controls can implement `make_custom_tooltip` to provide their own tooltip.
+	// This should be a Control node which will be added as child to a TooltipPanel.
+	Control *base_tooltip = which->make_custom_tooltip(tooltip_text);


Perhaps should be named base_tooltip_control just to follow suit.

I'm not sure this would be really useful as it's only used locally and it's clear from it's type declaration. This would also open the door to renaming make_custom_tooltip and tons of tooltip-related methods which can either be about tooltip widgets or tooltip texts in the existing API.

Yeah. you are right. Better not go down the rabbit hole.

rxlecky · 2020-11-02T22:04:51Z

Changes look good to me all in all. The docs are definitely clearer now and the extra section on theming tooltips is great, I didn't know that.

Also, I'd like to bring up my argument from #39677 (comment) and say that if user returns a custom tooltip Control with visible = false and there is an edge case that causes unexpected behaviour under that conditions, we should just show empty TooltipPanel. That is more of an expected behaviour than showing a tooltip which is half-cropped by window edge. I, as a user, would consider that behaviour an engine bug, rather than user error. Even though the docs are now explicitly flagging this, there will be many people who won't read it and will instead report issues about supposedly bugged tooltips.

I feel like there are three main ways we can communicate with the user, in order of accessibility:

Behaviour
Output console
Documentation

If we make the first point of contact, behaviour, confusing by showing unexpected, half-cropped tooltip, we haven't communicated the cause of the problem to the user very well. If we instead show empty tooltip panel, the user might either get a hint that their tooltip is not set to visible or it will prompt them to read the documentation where they will find answer to why tooltip is empty.

akien-mga · 2020-11-03T08:12:48Z

Also, I'd like to bring up my argument from #39677 (comment) and say that if user returns a custom tooltip Control with visible = false and there is an edge case that causes unexpected behaviour under that conditions, we should just show empty TooltipPanel. That is more of an expected behaviour than showing a tooltip which is half-cropped by window edge. I, as a user, would consider that behaviour an engine bug, rather than user error. Even though the docs are now explicitly flagging this, there will be many people who won't read it and will instead report issues about supposedly bugged tooltips.

In the master branch, this is actually what happens. It's only the TooltipPanel created by the engine that gets show()-ed, the Control you pass from make_custom_tooltip() is not impacted. So if it's not visible, you will indeed see an empty panel (contrarily to 3.2 where show() is called on the custom Control).

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 godotengine#39677.

rxlecky · 2020-11-03T11:55:55Z

Oh, sorry, didn't realize that. That's good then. Perhaps we should replicate that behaviour in 3.2 when backporting this change.

akien-mga · 2020-11-11T14:00:19Z

Cherry-picked for 3.2.4.

Perhaps we should replicate that behaviour in 3.2 when backporting this change.

I chose not to as this could be considered a breaking change. IMO the fact that I was the one to report this issue even though I don't work on any serious Godot project apart from the engine itself shows that there are probably not too many users affected by this, so the documentation change should be enough for those.

akien-mga · 2021-01-05T14:01:43Z

scene/main/viewport.cpp

+			gui.tooltip_control,
+			gui.tooltip_control->get_global_transform().xform_inv(gui.last_mouse_pos),
+			&tooltip_owner);
+	tooltip_text.strip_edges();


I introduced a bug here, this doesn't do anything as it's not assigned.

Fixes godotengine#43940, was a regression from godotengine#43280.

Fixes godotengine#43940, was a regression from godotengine#43280. (cherry picked from commit a4af940)

akien-mga added enhancement documentation cherrypick:3.x Considered for cherry-picking into a future 3.x release topic:gui labels Nov 2, 2020

akien-mga added this to the 4.0 milestone Nov 2, 2020

akien-mga requested a review from a team as a code owner November 2, 2020 19:15

akien-mga mentioned this pull request Nov 2, 2020

doc: Clarify documentation for Control._make_custom_tooltip #43273

Closed

akien-mga commented Nov 2, 2020

View reviewed changes

akien-mga force-pushed the custom-tooltips-cleanup branch from d8ecc74 to 078a98b Compare November 2, 2020 19:18

rxlecky reviewed Nov 2, 2020

View reviewed changes

akien-mga force-pushed the custom-tooltips-cleanup branch from 078a98b to 18380c3 Compare November 3, 2020 08:10

akien-mga force-pushed the custom-tooltips-cleanup branch from 18380c3 to c5d8daf Compare November 3, 2020 08:19

akien-mga merged commit 0fc84b7 into godotengine:master Nov 3, 2020

akien-mga deleted the custom-tooltips-cleanup branch November 3, 2020 12:09

akien-mga removed the cherrypick:3.x Considered for cherry-picking into a future 3.x release label Nov 11, 2020

akien-mga mentioned this pull request Jan 5, 2021

Tooltips for some 3D editor functions contain an additional newline. #43940

Closed

akien-mga commented Jan 5, 2021

View reviewed changes

akien-mga added a commit to akien-mga/godot that referenced this pull request Jan 5, 2021

Tooltips: Fix unassigned strip_edges() call on text

a4af940

Fixes godotengine#43940, was a regression from godotengine#43280.

akien-mga mentioned this pull request Jan 5, 2021

Tooltips: Fix unassigned strip_edges() call on text #44936

Merged

akien-mga added a commit to akien-mga/godot that referenced this pull request Jan 5, 2021

Tooltips: Fix unassigned strip_edges() call on text

08ecc9e

Fixes godotengine#43940, was a regression from godotengine#43280. (cherry picked from commit a4af940)

akien-mga mentioned this pull request May 12, 2021

Editor tooltips should be constrained inside the editor window even at the bottom of the UI #48656

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tooltips: Improve code clarity and docs #43280

Tooltips: Improve code clarity and docs #43280

akien-mga commented Nov 2, 2020

akien-mga commented Nov 2, 2020

akien-mga Nov 2, 2020

rxlecky Nov 2, 2020

akien-mga Nov 3, 2020

rxlecky Nov 2, 2020

akien-mga Nov 3, 2020

rxlecky Nov 3, 2020

rxlecky commented Nov 2, 2020

akien-mga commented Nov 3, 2020

rxlecky commented Nov 3, 2020

akien-mga commented Nov 11, 2020

akien-mga Jan 5, 2021

Tooltips: Improve code clarity and docs #43280

Tooltips: Improve code clarity and docs #43280

Conversation

akien-mga commented Nov 2, 2020

akien-mga commented Nov 2, 2020

akien-mga Nov 2, 2020

Choose a reason for hiding this comment

rxlecky Nov 2, 2020

Choose a reason for hiding this comment

akien-mga Nov 3, 2020

Choose a reason for hiding this comment

rxlecky Nov 2, 2020

Choose a reason for hiding this comment

akien-mga Nov 3, 2020

Choose a reason for hiding this comment

rxlecky Nov 3, 2020

Choose a reason for hiding this comment

rxlecky commented Nov 2, 2020

akien-mga commented Nov 3, 2020

rxlecky commented Nov 3, 2020

akien-mga commented Nov 11, 2020

akien-mga Jan 5, 2021

Choose a reason for hiding this comment