Add utility methods to Theme, improve error messages and documentation

1 files changed, 206 insertions, 6 deletions

diff --git a/doc/classes/Theme.xml b/doc/classes/Theme.xml
index 9f976838e9..ad22573eb8 100644
--- a/doc/classes/Theme.xml
+++ b/doc/classes/Theme.xml
@@ -84,6 +84,19 @@
 				Clears [StyleBox] at [code]name[/code] if the theme has [code]node_type[/code].
 			</description>
 		</method>
+		<method name="clear_theme_item">
+			<return type="void">
+			</return>
+			<argument index="0" name="data_type" type="int" enum="Theme.DataType">
+			</argument>
+			<argument index="1" name="name" type="StringName">
+			</argument>
+			<argument index="2" name="node_type" type="StringName">
+			</argument>
+			<description>
+				Clears the theme item of [code]data_type[/code] at [code]name[/code] if the theme has [code]node_type[/code].
+			</description>
+		</method>
 		<method name="copy_default_theme">
 			<return type="void">
 			</return>
@@ -194,6 +207,13 @@
 				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]node_type[/code].
 			</description>
 		</method>
+		<method name="get_font_size_type_list" qualifiers="const">
+			<return type="PackedStringArray">
+			</return>
+			<description>
+				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].
+			</description>
+		</method>
 		<method name="get_font_type_list" qualifiers="const">
 			<return type="PackedStringArray">
 			</return>
@@ -257,6 +277,41 @@
 				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].
 			</description>
 		</method>
+		<method name="get_theme_item" qualifiers="const">
+			<return type="StyleBox">
+			</return>
+			<argument index="0" name="data_type" type="int" enum="Theme.DataType">
+			</argument>
+			<argument index="1" name="name" type="StringName">
+			</argument>
+			<argument index="2" name="node_type" type="StringName">
+			</argument>
+			<description>
+				Returns the theme item of [code]data_type[/code] at [code]name[/code] if the theme has [code]node_type[/code].
+				Valid [code]name[/code]s may be found using [method get_theme_item_list] or a data type specific method. Valid [code]node_type[/code]s may be found using [method get_theme_item_type_list] or a data type specific method.
+			</description>
+		</method>
+		<method name="get_theme_item_list" qualifiers="const">
+			<return type="PackedStringArray">
+			</return>
+			<argument index="0" name="data_type" type="int" enum="Theme.DataType">
+			</argument>
+			<argument index="1" name="node_type" type="String">
+			</argument>
+			<description>
+				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]node_type[/code].
+				Valid [code]node_type[/code]s may be found using [method get_theme_item_type_list] or a data type specific method.
+			</description>
+		</method>
+		<method name="get_theme_item_type_list" qualifiers="const">
+			<return type="PackedStringArray">
+			</return>
+			<argument index="0" name="data_type" type="int" enum="Theme.DataType">
+			</argument>
+			<description>
+				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.
+			</description>
+		</method>
 		<method name="get_type_list" qualifiers="const">
 			<return type="PackedStringArray">
 			</return>
@@ -336,6 +391,113 @@
 				Returns [code]false[/code] if the theme does not have [code]node_type[/code].
 			</description>
 		</method>
+		<method name="has_theme_item" qualifiers="const">
+			<return type="bool">
+			</return>
+			<argument index="0" name="data_type" type="int" enum="Theme.DataType">
+			</argument>
+			<argument index="1" name="name" type="StringName">
+			</argument>
+			<argument index="2" name="node_type" type="StringName">
+			</argument>
+			<description>
+				Returns [code]true[/code] if a theme item of [code]data_type[/code] with [code]name[/code] is in [code]node_type[/code].
+				Returns [code]false[/code] if the theme does not have [code]node_type[/code].
+			</description>
+		</method>
+		<method name="rename_color">
+			<return type="void">
+			</return>
+			<argument index="0" name="old_name" type="StringName">
+			</argument>
+			<argument index="1" name="name" type="StringName">
+			</argument>
+			<argument index="2" name="node_type" type="StringName">
+			</argument>
+			<description>
+				Renames the [Color] at [code]old_name[/code] to [code]name[/code] if the theme has [code]node_type[/code]. If [code]name[/code] is already taken, this method fails.
+			</description>
+		</method>
+		<method name="rename_constant">
+			<return type="void">
+			</return>
+			<argument index="0" name="old_name" type="StringName">
+			</argument>
+			<argument index="1" name="name" type="StringName">
+			</argument>
+			<argument index="2" name="node_type" type="StringName">
+			</argument>
+			<description>
+				Renames the constant at [code]old_name[/code] to [code]name[/code] if the theme has [code]node_type[/code]. If [code]name[/code] is already taken, this method fails.
+			</description>
+		</method>
+		<method name="rename_font">
+			<return type="void">
+			</return>
+			<argument index="0" name="old_name" type="StringName">
+			</argument>
+			<argument index="1" name="name" type="StringName">
+			</argument>
+			<argument index="2" name="node_type" type="StringName">
+			</argument>
+			<description>
+				Renames the [Font] at [code]old_name[/code] to [code]name[/code] if the theme has [code]node_type[/code]. If [code]name[/code] is already taken, this method fails.
+			</description>
+		</method>
+		<method name="rename_font_size">
+			<return type="void">
+			</return>
+			<argument index="0" name="old_name" type="StringName">
+			</argument>
+			<argument index="1" name="name" type="StringName">
+			</argument>
+			<argument index="2" name="node_type" type="StringName">
+			</argument>
+			<description>
+				Renames the font size [code]old_name[/code] to [code]name[/code] if the theme has [code]node_type[/code]. If [code]name[/code] is already taken, this method fails.
+			</description>
+		</method>
+		<method name="rename_icon">
+			<return type="void">
+			</return>
+			<argument index="0" name="old_name" type="StringName">
+			</argument>
+			<argument index="1" name="name" type="StringName">
+			</argument>
+			<argument index="2" name="node_type" type="StringName">
+			</argument>
+			<description>
+				Renames the icon at [code]old_name[/code] to [code]name[/code] if the theme has [code]node_type[/code]. If [code]name[/code] is already taken, this method fails.
+			</description>
+		</method>
+		<method name="rename_stylebox">
+			<return type="void">
+			</return>
+			<argument index="0" name="old_name" type="StringName">
+			</argument>
+			<argument index="1" name="name" type="StringName">
+			</argument>
+			<argument index="2" name="node_type" type="StringName">
+			</argument>
+			<description>
+				Renames [StyleBox] at [code]old_name[/code] to [code]name[/code] if the theme has [code]node_type[/code]. If [code]name[/code] is already taken, this method fails.
+			</description>
+		</method>
+		<method name="rename_theme_item">
+			<return type="void">
+			</return>
+			<argument index="0" name="data_type" type="int" enum="Theme.DataType">
+			</argument>
+			<argument index="1" name="old_name" type="StringName">
+			</argument>
+			<argument index="2" name="name" type="StringName">
+			</argument>
+			<argument index="3" name="node_type" type="StringName">
+			</argument>
+			<description>
+				Renames the theme item of [code]data_type[/code] at [code]old_name[/code] to [code]name[/code] if the theme has [code]node_type[/code]. If [code]name[/code] is already taken, this method fails.
+			</description>
+		</method>
 		<method name="set_color">
 			<return type="void">
 			</return>
@@ -347,7 +509,7 @@
 			</argument>
 			<description>
 				Sets the theme's [Color] to [code]color[/code] at [code]name[/code] in [code]node_type[/code].
-				Does nothing if the theme does not have [code]node_type[/code].
+				Creates [code]node_type[/code] if the theme does not have it.
 			</description>
 		</method>
 		<method name="set_constant">
@@ -361,7 +523,7 @@
 			</argument>
 			<description>
 				Sets the theme's constant to [code]constant[/code] at [code]name[/code] in [code]node_type[/code].
-				Does nothing if the theme does not have [code]node_type[/code].
+				Creates [code]node_type[/code] if the theme does not have it.
 			</description>
 		</method>
 		<method name="set_font">
@@ -375,7 +537,7 @@
 			</argument>
 			<description>
 				Sets the theme's [Font] to [code]font[/code] at [code]name[/code] in [code]node_type[/code].
-				Does nothing if the theme does not have [code]node_type[/code].
+				Creates [code]node_type[/code] if the theme does not have it.
 			</description>
 		</method>
 		<method name="set_font_size">
@@ -389,7 +551,7 @@
 			</argument>
 			<description>
 				Sets the theme's font size to [code]font_size[/code] at [code]name[/code] in [code]node_type[/code].
-				Does nothing if the theme does not have [code]node_type[/code].
+				Creates [code]node_type[/code] if the theme does not have it.
 			</description>
 		</method>
 		<method name="set_icon">
@@ -403,7 +565,7 @@
 			</argument>
 			<description>
 				Sets the theme's icon [Texture2D] to [code]texture[/code] at [code]name[/code] in [code]node_type[/code].
-				Does nothing if the theme does not have [code]node_type[/code].
+				Creates [code]node_type[/code] if the theme does not have it.
 			</description>
 		</method>
 		<method name="set_stylebox">
@@ -417,7 +579,24 @@
 			</argument>
 			<description>
 				Sets theme's [StyleBox] to [code]stylebox[/code] at [code]name[/code] in [code]node_type[/code].
-				Does nothing if the theme does not have [code]node_type[/code].
+				Creates [code]node_type[/code] if the theme does not have it.
+			</description>
+		</method>
+		<method name="set_theme_item">
+			<return type="void">
+			</return>
+			<argument index="0" name="data_type" type="int" enum="Theme.DataType">
+			</argument>
+			<argument index="1" name="name" type="StringName">
+			</argument>
+			<argument index="2" name="node_type" type="StringName">
+			</argument>
+			<argument index="3" name="value" type="Variant">
+			</argument>
+			<description>
+				Sets the theme item of [code]data_type[/code] to [code]value[/code] at [code]name[/code] in [code]node_type[/code].
+				Does nothing if the [code]value[/code] type does not match [code]data_type[/code].
+				Creates [code]node_type[/code] if the theme does not have it.
 			</description>
 		</method>
 	</methods>
@@ -430,5 +609,26 @@
 		</member>
 	</members>
 	<constants>
+		<constant name="DATA_TYPE_COLOR" value="0" enum="DataType">
+			Theme's [Color] item type.
+		</constant>
+		<constant name="DATA_TYPE_CONSTANT" value="1" enum="DataType">
+			Theme's constant item type.
+		</constant>
+		<constant name="DATA_TYPE_FONT" value="2" enum="DataType">
+			Theme's [Font] item type.
+		</constant>
+		<constant name="DATA_TYPE_FONT_SIZE" value="3" enum="DataType">
+			Theme's font size item type.
+		</constant>
+		<constant name="DATA_TYPE_ICON" value="4" enum="DataType">
+			Theme's icon [Texture2D] item type.
+		</constant>
+		<constant name="DATA_TYPE_STYLEBOX" value="5" enum="DataType">
+			Theme's [StyleBox] item type.
+		</constant>
+		<constant name="DATA_TYPE_MAX" value="6" enum="DataType">
+			Maximum value for the DataType enum.
+		</constant>
 	</constants>
 </class>