Docs: Update Control class to properly reflect behavior of Themes on Control Children #99620
Conversation
doc/classes/Control.xml
Outdated
| @@ -12,7 +12,7 @@ | |||
| Call [method accept_event] so no other node receives the event. Once you accept an input, it becomes handled so [method Node._unhandled_input] will not process it. | |||
| Only one [Control] node can be in focus. Only the node in focus will receive events. To get the focus, call [method grab_focus]. [Control] nodes lose focus when another node grabs it, or if you hide the node in focus. | |||
| Sets [member mouse_filter] to [constant MOUSE_FILTER_IGNORE] to tell a [Control] node to ignore mouse or touch events. You'll need it if you place an icon on top of a button. | |||
| [Theme] resources change the Control's appearance. If you change the [Theme] on a [Control] node, it affects all of its children. To override some of the theme's parameters, call one of the [code]add_theme_*_override[/code] methods, like [method add_theme_font_override]. You can override the theme with the Inspector. | |||
| [Theme] resources change the [Control]'s appearance. The [member theme] of a [Control] node affects all of its direct and indirect children (as long as a chain of [Control]s is uninterrupted). To override some of the theme items, call one of the [code]add_theme_*_override[/code] methods, like [method add_theme_font_override]. | |||
There was a problem hiding this comment.
| [Theme] resources change the [Control]'s appearance. The [member theme] of a [Control] node affects all of its direct and indirect children (as long as a chain of [Control]s is uninterrupted). To override some of the theme items, call one of the [code]add_theme_*_override[/code] methods, like [method add_theme_font_override]. | |
| [Theme] resources change the control's appearance. The [member theme] of a [Control] node affects all of its direct and indirect children (as long as a chain of controls is uninterrupted). To override some of the theme items, call one of the [code]add_theme_*_override[/code] methods, like [method add_theme_font_override]. |
I think this is a little better personally, but since the salvaged PR already had an applied suggestion to use "[Control]" instead of "control" I left it in (and added brackets to the untagged capitalized "Control").
There was a problem hiding this comment.
Doing this has always been better in my opinion, yes.
There was a problem hiding this comment.
Applied this change, but willing to revert if it's contentious.
We should probably formalize some actual guidelines for when to use "control" vs "[Control]" at some point, otherwise ambiguous situations like this are likely to be changed back and forth repeatedly.
|
The documentation is sometimes torn on what to call these. Sometimes it's "theme items" and sometimes it's "theme properties". I think the former is more common. |
doc/classes/Control.xml
Outdated
| @@ -12,7 +12,7 @@ | |||
| Call [method accept_event] so no other node receives the event. Once you accept an input, it becomes handled so [method Node._unhandled_input] will not process it. | |||
| Only one [Control] node can be in focus. Only the node in focus will receive events. To get the focus, call [method grab_focus]. [Control] nodes lose focus when another node grabs it, or if you hide the node in focus. | |||
| Sets [member mouse_filter] to [constant MOUSE_FILTER_IGNORE] to tell a [Control] node to ignore mouse or touch events. You'll need it if you place an icon on top of a button. | |||
| [Theme] resources change the Control's appearance. If you change the [Theme] on a [Control] node, it affects all of its children. To override some of the theme's parameters, call one of the [code]add_theme_*_override[/code] methods, like [method add_theme_font_override]. You can override the theme with the Inspector. | |||
| [Theme] resources change the [Control]'s appearance. The [member theme] of a [Control] node affects all of its direct and indirect children (as long as a chain of [Control]s is uninterrupted). To override some of the theme items, call one of the [code]add_theme_*_override[/code] methods, like [method add_theme_font_override]. | |||
There was a problem hiding this comment.
I think it's worth lightly mentioning they can be overridden in the Inspector dock, as per the original description.
There was a problem hiding this comment.
Should I restore the original phrasing " You can override the theme with the Inspector.", then?
Or were you thinking incorporate it into another of the sentences
There was a problem hiding this comment.
Something like "It's also possible to override theme items in the Inspector." or "You can override theme items in the Inspector". The prior sentence is exactly about this, and it's very much for granted that theme can be changed in the Inspector like most properties.
There was a problem hiding this comment.
I went with the second suggestion.
…Control Children Document fact that themes only propagate to control children (not Node2D, etc). Wording is copied from Theme docs. Also clarifies line somewhat. Co-Authored-By: Allyson Chan <[email protected]>
tetrapod00
force-pushed
the
doc-control-children
branch
from
53ca7b9 to
13b565c
Compare
|
Thanks! |
Supersedes #90289. Apologies if this kind of salvage is frowned upon in the main repo; I've been doing this to clear the backlog in the docs repo recently.
Closes #88534.
The wording "as long as a chain of [Control]s is uninterrupted" is copied from the Theme docs.
I made some additional changes:
themeproperty.[member theme].