From 54b47b8fa6c8d26351b531d63131ea41e3772164 Mon Sep 17 00:00:00 2001 From: Yuri Sizov Date: Tue, 1 Feb 2022 18:43:53 +0300 Subject: Refine Theme documentation to make it more factual --- doc/classes/Theme.xml | 200 ++++++++++++++++++++++++++++---------------------- 1 file changed, 112 insertions(+), 88 deletions(-) (limited to 'doc/classes') diff --git a/doc/classes/Theme.xml b/doc/classes/Theme.xml index d1a48fda55..b1367be263 100644 --- a/doc/classes/Theme.xml +++ b/doc/classes/Theme.xml @@ -1,20 +1,22 @@ - Theme for controls. + Theme resource for styling/skinning [Control]s and [Window]s. - A theme for skinning controls. Controls can be skinned individually, but for complex applications, it's more practical to just create a global theme that defines everything. This theme can be applied to any [Control]; the Control and its children will automatically use it. - Theme resources can alternatively be loaded by writing them in a [code].theme[/code] file, see the documentation for more information. + A theme resource is used for styling/skinning [Control] and [Window] nodes. While individual controls can be styled using their local theme overrides (see [method Control.add_theme_color_override]), theme resources allow you to store and apply the same settings between all controls sharing the same type (e.g. style all [Button]s the same). One theme resource can be used for the entire project, but you can also set a separate theme resource to a branch of control nodes. A theme resources assigned to a control node applies to the control itself, as well as all of its direct and indirect children (as long as a chain of controls is uninterrupted). + Use [member ProjectSettings.gui/theme/custom] to set up a project-scope theme that will be available to every control in your project. + Use [member Control.theme] of any control node to set up a theme that will be available to that control and all of its direct and indirect children. $DOCS_URL/tutorials/ui/gui_skinning.html + $DOCS_URL/tutorials/ui/gui_using_theme_editor.html - Clears all values on the theme. + Removes all the theme properties defined on the theme resource. @@ -22,7 +24,8 @@ - Clears the [Color] at [code]name[/code] if the theme has [code]theme_type[/code]. + Removes the [Color] property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Fails if it doesn't exist. Use [method has_color] to check for existence. @@ -30,7 +33,8 @@ - Clears the constant at [code]name[/code] if the theme has [code]theme_type[/code]. + Removes the constant property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Fails if it doesn't exist. Use [method has_constant] to check for existence. @@ -38,7 +42,8 @@ - Clears the [Font] at [code]name[/code] if the theme has [code]theme_type[/code]. + Removes the [Font] property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Fails if it doesn't exist. Use [method has_font] to check for existence. @@ -46,7 +51,8 @@ - Clears the font size [code]name[/code] if the theme has [code]theme_type[/code]. + Removes the font size property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Fails if it doesn't exist. Use [method has_font_size] to check for existence. @@ -54,7 +60,8 @@ - Clears the icon at [code]name[/code] if the theme has [code]theme_type[/code]. + Removes the icon property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Fails if it doesn't exist. Use [method has_icon] to check for existence. @@ -62,7 +69,8 @@ - Clears [StyleBox] at [code]name[/code] if the theme has [code]theme_type[/code]. + Removes the [StyleBox] property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Fails if it doesn't exist. Use [method has_stylebox] to check for existence. @@ -71,14 +79,16 @@ - Clears the theme item of [code]data_type[/code] at [code]name[/code] if the theme has [code]theme_type[/code]. + Removes the theme property of [code]data_type[/code] defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Fails if it doesn't exist. Use [method has_theme_item] to check for existence. + [b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic. - Unmarks [code]theme_type[/code] as being a variation of any other type. + Unmarks [code]theme_type[/code] as being a variation of another theme type. See [method set_type_variation]. @@ -86,20 +96,21 @@ - Returns the [Color] at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the [Color] property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Returns the default color value if the property doesn't exist. Use [method has_color] to check for existence. - Returns all the [Color]s as a [PackedStringArray] filled with each [Color]'s name, for use in [method get_color], if the theme has [code]theme_type[/code]. + Returns a list of names for [Color] properties defined with [code]theme_type[/code]. Use [method get_color_type_list] to get a list of possible theme type names. - Returns all the [Color] types as a [PackedStringArray] filled with unique type names, for use in [method get_color] and/or [method get_color_list]. + Returns a list of all unique theme type names for [Color] properties. Use [method get_type_list] to get a list of all unique theme types. @@ -107,20 +118,21 @@ - Returns the constant at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the constant property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Returns [code]0[/code] if the property doesn't exist. Use [method has_constant] to check for existence. - Returns all the constants as a [PackedStringArray] filled with each constant's name, for use in [method get_constant], if the theme has [code]theme_type[/code]. + Returns a list of names for constant properties defined with [code]theme_type[/code]. Use [method get_constant_type_list] to get a list of possible theme type names. - Returns all the constant types as a [PackedStringArray] filled with unique type names, for use in [method get_constant] and/or [method get_constant_list]. + Returns a list of all unique theme type names for constant properties. Use [method get_type_list] to get a list of all unique theme types. @@ -128,14 +140,16 @@ - Returns the [Font] at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the [Font] property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Returns the default theme font if the property doesn't exist and the default theme font is set up (see [member default_font]). Use [method has_font] to check for existence of the property and [method has_default_font] to check for existence of the default theme font. + Returns the engine fallback font value, if neither exist. - Returns all the [Font]s as a [PackedStringArray] filled with each [Font]'s name, for use in [method get_font], if the theme has [code]theme_type[/code]. + Returns a list of names for [Font] properties defined with [code]theme_type[/code]. Use [method get_font_type_list] to get a list of possible theme type names. @@ -143,26 +157,28 @@ - Returns the font size at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the font size property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Returns the default theme font size if the property doesn't exist and the default theme font size is set up (see [member default_font_size]). Use [method has_font_size] to check for existence of the property and [method has_default_font_size] to check for existence of the default theme font. + Returns the engine fallback font size value, if neither exist. - Returns all the font sizes as a [PackedStringArray] filled with each font size name, for use in [method get_font_size], if the theme has [code]theme_type[/code]. + Returns a list of names for font size properties defined with [code]theme_type[/code]. Use [method get_font_size_type_list] to get a list of possible theme type names. - Returns all the font size types as a [PackedStringArray] filled with unique type names, for use in [method get_font_size] and/or [method get_font_size_list]. + Returns a list of all unique theme type names for font size properties. Use [method get_type_list] to get a list of all unique theme types. - Returns all the [Font] types as a [PackedStringArray] filled with unique type names, for use in [method get_font] and/or [method get_font_list]. + Returns a list of all unique theme type names for [Font] properties. Use [method get_type_list] to get a list of all unique theme types. @@ -170,20 +186,21 @@ - Returns the icon [Texture2D] at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the icon property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Returns the engine fallback icon value if the property doesn't exist. Use [method has_icon] to check for existence. - Returns all the icons as a [PackedStringArray] filled with each [Texture2D]'s name, for use in [method get_icon], if the theme has [code]theme_type[/code]. + Returns a list of names for icon properties defined with [code]theme_type[/code]. Use [method get_icon_type_list] to get a list of possible theme type names. - Returns all the icon types as a [PackedStringArray] filled with unique type names, for use in [method get_icon] and/or [method get_icon_list]. + Returns a list of all unique theme type names for icon properties. Use [method get_type_list] to get a list of all unique theme types. @@ -191,22 +208,21 @@ - Returns the [StyleBox] at [code]name[/code] if the theme has [code]theme_type[/code]. - Valid [code]name[/code]s may be found using [method get_stylebox_list]. Valid [code]theme_type[/code]s may be found using [method get_stylebox_type_list]. + Returns the [StyleBox] property defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Returns the engine fallback stylebox value if the property doesn't exist. Use [method has_stylebox] to check for existence. - Returns all the [StyleBox]s as a [PackedStringArray] filled with each [StyleBox]'s name, for use in [method get_stylebox], if the theme has [code]theme_type[/code]. - Valid [code]theme_type[/code]s may be found using [method get_stylebox_type_list]. + Returns a list of names for [StyleBox] properties defined with [code]theme_type[/code]. Use [method get_stylebox_type_list] to get a list of possible theme type names. - Returns all the [StyleBox] types as a [PackedStringArray] filled with unique type names, for use in [method get_stylebox] and/or [method get_stylebox_list]. + Returns a list of all unique theme type names for [StyleBox] properties. Use [method get_type_list] to get a list of all unique theme types. @@ -215,8 +231,9 @@ - Returns the theme item of [code]data_type[/code] at [code]name[/code] if the theme has [code]theme_type[/code]. - Valid [code]name[/code]s may be found using [method get_theme_item_list] or a data type specific method. Valid [code]theme_type[/code]s may be found using [method get_theme_item_type_list] or a data type specific method. + Returns the theme property of [code]data_type[/code] defined by [code]name[/code] and [code]theme_type[/code], if it exists. + Returns the engine fallback icon value if the property doesn't exist. Use [method has_theme_item] to check for existence. + [b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic. @@ -224,35 +241,36 @@ - Returns all the theme items of [code]data_type[/code] as a [PackedStringArray] filled with each theme items's name, for use in [method get_theme_item] or a data type specific method, if the theme has [code]theme_type[/code]. - Valid [code]theme_type[/code]s may be found using [method get_theme_item_type_list] or a data type specific method. + Returns a list of names for properties of [code]data_type[/code] defined with [code]theme_type[/code]. Use [method get_theme_item_type_list] to get a list of possible theme type names. + [b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic. - Returns all the theme items of [code]data_type[/code] types as a [PackedStringArray] filled with unique type names, for use in [method get_theme_item], [method get_theme_item_list] or data type specific methods. + Returns a list of all unique theme type names for [code]data_type[/code] properties. Use [method get_type_list] to get a list of all unique theme types. + [b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic. - Returns all the theme types as a [PackedStringArray] filled with unique type names, for use in other [code]get_*[/code] functions of this theme. + Returns a list of all unique theme type names. Use the appropriate [code]get_*_type_list[/code] method to get a list of unique theme types for a single data type. - Returns the base theme type if [code]theme_type[/code] is a valid variation type. Returns an empty string otherwise. + Returns the name of the base theme type if [code]theme_type[/code] is a valid variation type. Returns an empty string otherwise. - Returns a list of all variation for the given [code]base_type[/code]. + Returns a list of all type variations for the given [code]base_type[/code]. @@ -260,8 +278,8 @@ - Returns [code]true[/code] if [Color] with [code]name[/code] is in [code]theme_type[/code]. - Returns [code]false[/code] if the theme does not have [code]theme_type[/code]. + Returns [code]true[/code] if the [Color] property defined by [code]name[/code] and [code]theme_type[/code] exists. + Returns [code]false[/code] if it doesn't exist. Use [method set_color] to define it. @@ -269,26 +287,29 @@ - Returns [code]true[/code] if constant with [code]name[/code] is in [code]theme_type[/code]. - Returns [code]false[/code] if the theme does not have [code]theme_type[/code]. + Returns [code]true[/code] if the constant property defined by [code]name[/code] and [code]theme_type[/code] exists. + Returns [code]false[/code] if it doesn't exist. Use [method set_constant] to define it. - Returns [code]true[/code] if this theme has a valid [member default_base_scale] value. + Returns [code]true[/code] if [member default_base_scale] has a valid value. + Returns [code]false[/code] if it doesn't. The value must be greater than [code]0.0[/code] to be considered valid. - Returns [code]true[/code] if this theme has a valid [member default_font] value. + Returns [code]true[/code] if [member default_font] has a valid value. + Returns [code]false[/code] if it doesn't. - Returns [code]true[/code] if this theme has a valid [member default_font_size] value. + Returns [code]true[/code] if [member default_font_size] has a valid value. + Returns [code]false[/code] if it doesn't. The value must be greater than [code]0[/code] to be considered valid. @@ -296,8 +317,8 @@ - Returns [code]true[/code] if [Font] with [code]name[/code] is in [code]theme_type[/code]. - Returns [code]false[/code] if the theme does not have [code]theme_type[/code]. + Returns [code]true[/code] if the [Font] property defined by [code]name[/code] and [code]theme_type[/code] exists, or if the default theme font is set up (see [method has_default_font]). + Returns [code]false[/code] if neither exist. Use [method set_font] to define the property. @@ -305,8 +326,8 @@ - Returns [code]true[/code] if font size with [code]name[/code] is in [code]theme_type[/code]. - Returns [code]false[/code] if the theme does not have [code]theme_type[/code]. + Returns [code]true[/code] if the font size property defined by [code]name[/code] and [code]theme_type[/code] exists, or if the default theme font size is set up (see [method has_default_font_size]). + Returns [code]false[/code] if neither exist. Use [method set_font_size] to define the property. @@ -314,8 +335,8 @@ - Returns [code]true[/code] if icon [Texture2D] with [code]name[/code] is in [code]theme_type[/code]. - Returns [code]false[/code] if the theme does not have [code]theme_type[/code]. + Returns [code]true[/code] if the icon property defined by [code]name[/code] and [code]theme_type[/code] exists. + Returns [code]false[/code] if it doesn't exist. Use [method set_icon] to define it. @@ -323,8 +344,8 @@ - Returns [code]true[/code] if [StyleBox] with [code]name[/code] is in [code]theme_type[/code]. - Returns [code]false[/code] if the theme does not have [code]theme_type[/code]. + Returns [code]true[/code] if the [StyleBox] property defined by [code]name[/code] and [code]theme_type[/code] exists. + Returns [code]false[/code] if it doesn't exist. Use [method set_stylebox] to define it. @@ -333,8 +354,9 @@ - Returns [code]true[/code] if a theme item of [code]data_type[/code] with [code]name[/code] is in [code]theme_type[/code]. - Returns [code]false[/code] if the theme does not have [code]theme_type[/code]. + Returns [code]true[/code] if the theme property of [code]data_type[/code] defined by [code]name[/code] and [code]theme_type[/code] exists. + Returns [code]false[/code] if it doesn't exist. Use [method set_theme_item] to define it. + [b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic. @@ -342,14 +364,14 @@ - Returns [code]true[/code] if [code]theme_type[/code] is marked as a variation of [code]base_type[/code] in this theme. + Returns [code]true[/code] if [code]theme_type[/code] is marked as a variation of [code]base_type[/code]. - Adds missing and overrides existing definitions with values from the [code]other[/code] [Theme]. + Adds missing and overrides existing definitions with values from the [code]other[/code] theme resource. [b]Note:[/b] This modifies the current theme. If you want to merge two themes together without modifying either one, create a new empty theme and merge the other two into it one after another. @@ -359,7 +381,8 @@ - Renames the [Color] at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails. + Renames the [Color] property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists. + Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_color] to check for existence, and [method clear_color] to remove the existing property. @@ -368,7 +391,8 @@ - Renames the constant at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails. + Renames the constant property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists. + Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_constant] to check for existence, and [method clear_constant] to remove the existing property. @@ -377,7 +401,8 @@ - Renames the [Font] at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails. + Renames the [Font] property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists. + Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_font] to check for existence, and [method clear_font] to remove the existing property. @@ -386,7 +411,8 @@ - Renames the font size [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails. + Renames the font size property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists. + Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_font_size] to check for existence, and [method clear_font_size] to remove the existing property. @@ -395,7 +421,8 @@ - Renames the icon at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails. + Renames the icon property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists. + Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_icon] to check for existence, and [method clear_icon] to remove the existing property. @@ -404,7 +431,8 @@ - Renames [StyleBox] at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails. + Renames the [StyleBox] property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists. + Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_stylebox] to check for existence, and [method clear_stylebox] to remove the existing property. @@ -414,7 +442,9 @@ - Renames the theme item of [code]data_type[/code] at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails. + Renames the theme property of [code]data_type[/code] defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists. + Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_theme_item] to check for existence, and [method clear_theme_item] to remove the existing property. + [b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic. @@ -423,8 +453,7 @@ - Sets the theme's [Color] to [code]color[/code] at [code]name[/code] in [code]theme_type[/code]. - Creates [code]theme_type[/code] if the theme does not have it. + Creates or changes the value of the [Color] property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_color] to remove the property. @@ -433,8 +462,7 @@ - Sets the theme's constant to [code]constant[/code] at [code]name[/code] in [code]theme_type[/code]. - Creates [code]theme_type[/code] if the theme does not have it. + Creates or changes the value of the constant property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_constant] to remove the property. @@ -443,8 +471,7 @@ - Sets the theme's [Font] to [code]font[/code] at [code]name[/code] in [code]theme_type[/code]. - Creates [code]theme_type[/code] if the theme does not have it. + Creates or changes the value of the [Font] property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_font] to remove the property. @@ -453,8 +480,7 @@ - Sets the theme's font size to [code]font_size[/code] at [code]name[/code] in [code]theme_type[/code]. - Creates [code]theme_type[/code] if the theme does not have it. + Creates or changes the value of the font size property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_font_size] to remove the property. @@ -463,8 +489,7 @@ - Sets the theme's icon [Texture2D] to [code]texture[/code] at [code]name[/code] in [code]theme_type[/code]. - Creates [code]theme_type[/code] if the theme does not have it. + Creates or changes the value of the icon property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_icon] to remove the property. @@ -473,8 +498,7 @@ - Sets theme's [StyleBox] to [code]stylebox[/code] at [code]name[/code] in [code]theme_type[/code]. - Creates [code]theme_type[/code] if the theme does not have it. + Creates or changes the value of the [StyleBox] property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_stylebox] to remove the property. @@ -484,9 +508,9 @@ - Sets the theme item of [code]data_type[/code] to [code]value[/code] at [code]name[/code] in [code]theme_type[/code]. - Does nothing if the [code]value[/code] type does not match [code]data_type[/code]. - Creates [code]theme_type[/code] if the theme does not have it. + Creates or changes the value of the theme property of [code]data_type[/code] defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_theme_item] to remove the property. + Fails if the [code]value[/code] type is not accepted by [code]data_type[/code]. + [b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic. @@ -494,25 +518,25 @@ - Marks [code]theme_type[/code] as being a variation of [code]base_type[/code]. + Marks [code]theme_type[/code] as a variation of [code]base_type[/code]. This adds [code]theme_type[/code] as a suggested option for [member Control.theme_type_variation] on a [Control] that is of the [code]base_type[/code] class. - Variations can also be nested, i.e. [code]base_type[/code] can be another variation. If a chain of variations ends with a [code]base_type[/code] matching a class of a [Control], the whole chain is going to be suggested as options. - [b]Note:[/b] Suggestions only show up if this [Theme] is set as the project default theme. See [member ProjectSettings.gui/theme/custom]. + Variations can also be nested, i.e. [code]base_type[/code] can be another variation. If a chain of variations ends with a [code]base_type[/code] matching the class of the [Control], the whole chain is going to be suggested as options. + [b]Note:[/b] Suggestions only show up if this theme resource is set as the project default theme. See [member ProjectSettings.gui/theme/custom]. - The default base scale factor of this [Theme] resource. Used by some controls to scale their visual properties based on a global scale factor. If this value is set to [code]0.0[/code], the global scale factor is used. + The default base scale factor of this theme resource. Used by some controls to scale their visual properties based on the global scale factor. If this value is set to [code]0.0[/code], the global scale factor is used. Use [method has_default_base_scale] to check if this value is valid. - The default font of this [Theme] resource. Used as a fallback value for font items defined in this theme, but having invalid values. If this value is also invalid, the global default value is used. + The default font of this theme resource. Used as the default value when trying to fetch a font resource that doesn't exist in this theme or is in invalid state. If the default font is also missing or invalid, the engine fallback value is used. Use [method has_default_font] to check if this value is valid. - The default font size of this [Theme] resource. Used as a fallback value for font size items defined in this theme, but having invalid values. If this value is set to [code]-1[/code], the global default value is used. - Use [method has_default_font_size] to check if this value is valid. + The default font size of this theme resource. Used as the default value when trying to fetch a font size value that doesn't exist in this theme or is in invalid state. If the default font size is also missing or invalid, the engine fallback value is used. + Values below [code]0[/code] are invalid and can be used to unset the property. Use [method has_default_font_size] to check if this value is valid. -- cgit v1.2.3