Theme
继承: Resource < RefCounted < Object
用于样式化/皮肤化 Control 和 Window 的资源。
描述
用于样式化/皮肤化 Control 和 Window 节点的资源。控件可以使用本地的主题覆盖项进行单独的风格化(见 Control.add_theme_color_override),而主题资源则能够存储这些设置,在所有同类型的控件之间实现共享(例如将所有 Button 都设置为相同的风格)。主题资源可以在整个项目上使用,但你也可以为单独的一个控件节点分支设置不同的主题资源。为某个控件节点分配的主题资源不仅会对它自己生效,也会对它的所有直接和间接子节点生效(只要控件链没有中断)。
项目范围的主题请使用 ProjectSettings.gui/theme/custom 设置,这样项目中的所有控件就都能够使用。
控件节点的主题请使用 Control.theme 设置,这样该控件和它的所有直接和间接子节点就都能够使用。
教程
属性
| ||
|
方法
枚举
enum DataType: 🔗
DataType DATA_TYPE_COLOR = 0
主题的 Color 颜色项类型。
DataType DATA_TYPE_CONSTANT = 1
主题的常量项类型。
DataType DATA_TYPE_FONT = 2
主题的 Font 字体项类型。
DataType DATA_TYPE_FONT_SIZE = 3
主题的字体大小项类型。
DataType DATA_TYPE_ICON = 4
主题的图标 Texture2D 项类型。
DataType DATA_TYPE_STYLEBOX = 5
主题的 StyleBox 项目类型。
DataType DATA_TYPE_MAX = 6
数据类型枚举的最大值。
属性说明
float default_base_scale = 0.0
🔗
该主题资源的默认基础缩放系数。部分控件会用它来根据全局缩放系数对其视觉属性进行缩放。如果该值为 0.0
,则使用全局缩放系数(见 ThemeDB.fallback_base_scale)。
请使用 has_default_base_scale 来检查该值是否有效。
该主题资源的默认字体。尝试获取字体资源时,如果该主题中不存在或者为无效状态,则会用它作为默认值。如果默认字体也缺失或无效,则会使用引擎的回退值(见 ThemeDB.fallback_font)。
请使用 has_default_font 来检查该值是否有效。
该主题资源的默认字体大小。尝试获取字体大小时,如果该主题中不存在或者为无效状态,则会用它作为默认值。如果默认字体大小也缺失或无效,则会使用引擎的回退值(见 ThemeDB.fallback_font_size)。
小于 0
的值无效,可用于清除对该属性的设置。请使用 has_default_font_size 来检查该值是否有效。
方法说明
void add_type(theme_type: StringName) 🔗
为每一个有效的数据类型都添加一个空主题类型。
注意:空类型不会随该主题保存。这个方法的存在是为了对资源执行内存中的更改。请使用 set_*
方法添加主题项目。
void clear() 🔗
移除在该主题资源上定义的所有主题属性。
void clear_color(name: StringName, theme_type: StringName) 🔗
如果存在由 name
和 theme_type
定义的 Color 属性,则将其移除。
如果不存在则失败。请使用 has_color 检查是否存在。
void clear_constant(name: StringName, theme_type: StringName) 🔗
如果存在由 name
和 theme_type
定义的常量属性,则将其移除。
如果不存在则失败。请使用 has_constant 检查是否存在。
void clear_font(name: StringName, theme_type: StringName) 🔗
如果存在由 name
和 theme_type
定义的 Font 属性,则将其移除。
如果不存在则失败。请使用 has_font 检查是否存在。
void clear_font_size(name: StringName, theme_type: StringName) 🔗
如果存在由 name
和 theme_type
定义的字体大小属性,则将其移除。
如果不存在则失败。请使用 has_font_size 检查是否存在。
void clear_icon(name: StringName, theme_type: StringName) 🔗
如果存在由 name
和 theme_type
定义的图标属性,则将其移除。
如果不存在则失败。请使用 has_icon 检查是否存在。
void clear_stylebox(name: StringName, theme_type: StringName) 🔗
如果存在由 name
和 theme_type
定义的 StyleBox 属性,则将其移除。
如果不存在则失败。请使用 has_stylebox 检查是否存在。
void clear_theme_item(data_type: DataType, name: StringName, theme_type: StringName) 🔗
如果存在由 name
和 theme_type
定义的 data_type
属性,则将其移除。
如果不存在则失败。请使用 has_theme_item 检查是否存在。
注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。
void clear_type_variation(theme_type: StringName) 🔗
取消将主题类型 theme_type
标记为任何主题类型的变种。见 set_type_variation。
Color get_color(name: StringName, theme_type: StringName) const 🔗
如果存在由 name
和 theme_type
定义的 Color 属性,则将其返回。
如果不存在则返回默认颜色。请使用 has_color 检查是否存在。
PackedStringArray get_color_list(theme_type: String) const 🔗
返回为 theme_type
类型定义的 Color 属性的名称列表。请使用 get_color_type_list 获取可能的主题类型名称。
PackedStringArray get_color_type_list() const 🔗
返回 Color 属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。
int get_constant(name: StringName, theme_type: StringName) const 🔗
如果存在由 name
和 theme_type
定义的常量属性,则将其返回。
如果不存在则返回 0
。请使用 has_constant 检查是否存在。
PackedStringArray get_constant_list(theme_type: String) const 🔗
返回为 theme_type
类型定义的常量属性的名称列表。请使用 get_constant_type_list 获取可能的主题类型名称。
PackedStringArray get_constant_type_list() const 🔗
返回常量属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。
Font get_font(name: StringName, theme_type: StringName) const 🔗
如果存在由 name
和 theme_type
定义的 Font 属性,则将其返回。
如果不存在且存在默认主题字体,则返回默认主题字体(见 default_font)。请使用 has_font 检查是否存在,使用 has_default_font 检查默认主题字体是否存在。
如果两者都不存在,则返回引擎的回退字体值(见 ThemeDB.fallback_font)。
PackedStringArray get_font_list(theme_type: String) const 🔗
返回为 theme_type
类型定义的 Font 属性的名称列表。请使用 get_font_type_list 获取可能的主题类型名称。
int get_font_size(name: StringName, theme_type: StringName) const 🔗
如果存在由 name
和 theme_type
定义的字体大小属性,则将其返回。
如果不存在且存在默认主题字体大小,则返回默认主题字体大小(见 default_font_size)。请使用 has_font_size 检查是否存在,使用 has_default_font_size 检查默认主题字体大小是否存在。
如果两者都不存在,则返回引擎的回退字体大小值(见 ThemeDB.fallback_font_size)。
PackedStringArray get_font_size_list(theme_type: String) const 🔗
返回为 theme_type
类型定义的字体大小属性的名称列表。请使用 get_font_size_type_list 获取可能的主题类型名称。
PackedStringArray get_font_size_type_list() const 🔗
返回字体大小属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。
PackedStringArray get_font_type_list() const 🔗
返回 Font 属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。
Texture2D get_icon(name: StringName, theme_type: StringName) const 🔗
如果存在由 name
和 theme_type
定义的图标属性,则将其返回。
如果不存在则返回引擎的回退图标值(见 ThemeDB.fallback_icon)。请使用 has_icon 检查是否存在。
PackedStringArray get_icon_list(theme_type: String) const 🔗
返回为 theme_type
类型定义的图标属性的名称列表。请使用 get_icon_type_list 获取可能的主题类型名称。
PackedStringArray get_icon_type_list() const 🔗
返回图标属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。
StyleBox get_stylebox(name: StringName, theme_type: StringName) const 🔗
如果存在由 name
和 theme_type
定义的 StyleBox 属性,则将其返回。
如果不存在则返回引擎的回退样式盒值(见 ThemeDB.fallback_stylebox)。请使用 has_stylebox 检查是否存在。
PackedStringArray get_stylebox_list(theme_type: String) const 🔗
返回为 theme_type
类型定义的 StyleBox 属性的名称列表。请使用 get_stylebox_type_list 获取可能的主题类型名称。
PackedStringArray get_stylebox_type_list() const 🔗
返回 StyleBox 属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。
Variant get_theme_item(data_type: DataType, name: StringName, theme_type: StringName) const 🔗
如果存在由 name
和 theme_type
定义的 data_type
属性,则将其返回。
如果不存在则返回引擎的回退值(见 ThemeDB)。请使用 has_theme_item 检查是否存在。
注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。
PackedStringArray get_theme_item_list(data_type: DataType, theme_type: String) const 🔗
返回为 theme_type
类型定义的 data_type
属性的名称列表。请使用 get_theme_item_type_list 获取可能的主题类型名称。
注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。
PackedStringArray get_theme_item_type_list(data_type: DataType) const 🔗
返回 data_type
属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。
注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。
PackedStringArray get_type_list() const 🔗
返回所有唯一主题类型名称的列表。获取单一数据类型的唯一主题类型列表请使用对应的 get_*_type_list
方法。
StringName get_type_variation_base(theme_type: StringName) const 🔗
如果 theme_type
是有效的变种类型,则返回其基础主题类型的名称。否则返回空字符串。
PackedStringArray get_type_variation_list(base_type: StringName) const 🔗
返回给定基础类型 base_type
的所有类型变种列表。
bool has_color(name: StringName, theme_type: StringName) const 🔗
如果主题类型 theme_type
中存在名为 name
的 Color 属性,则返回 true
。
不存在时返回 false
。定义请使用 set_color。
bool has_constant(name: StringName, theme_type: StringName) const 🔗
如果主题类型 theme_type
中存在名为 name
的常量属性,则返回 true
。
不存在时返回 false
。定义请使用 set_constant。
bool has_default_base_scale() const 🔗
如果 default_base_scale 的值有效,则返回 true
。
如果无效则返回 false
。有效值必须大于 0.0
。
bool has_default_font() const 🔗
如果 default_font 的值有效,则返回 true
。
如果无效则返回 false
。
bool has_default_font_size() const 🔗
如果 default_font_size 的值有效,则返回 true
。
如果无效则返回 false
。有效值必须大于 0
。
bool has_font(name: StringName, theme_type: StringName) const 🔗
如果主题类型 theme_type
中存在名为 name
的 Font 属性,则返回 true
。
不存在时返回 false
。定义请使用 set_font。
bool has_font_size(name: StringName, theme_type: StringName) const 🔗
如果主题类型 theme_type
中存在名为 name
的字体大小属性,则返回 true
。
不存在时返回 false
。定义请使用 set_font_size。
bool has_icon(name: StringName, theme_type: StringName) const 🔗
如果主题类型 theme_type
中存在名为 name
的图标属性,则返回 true
。
不存在时返回 false
。定义请使用 set_icon。
bool has_stylebox(name: StringName, theme_type: StringName) const 🔗
如果主题类型 theme_type
中存在名为 name
的 StyleBox 属性,则返回 true
。
不存在时返回 false
。定义请使用 set_stylebox。
bool has_theme_item(data_type: DataType, name: StringName, theme_type: StringName) const 🔗
如果主题类型 theme_type
中存在名为 name
的主题属性,则返回 true
。
不存在时返回 false
。定义请使用 set_theme_item。
注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。
bool is_type_variation(theme_type: StringName, base_type: StringName) const 🔗
如果主题类型 theme_type
被标记为基础类型 base_type
的变种,则返回 true
。
void merge_with(other: Theme) 🔗
添加缺失的定义,并使用 other
主题资源中的值覆盖已有的定义。
注意:这修改了当前的主题。如果想将两个主题合并在一起且不修改任何一个,请创建一个新的空主题,并将其他两个依次合并到其中。
void remove_type(theme_type: StringName) 🔗
移除该主题类型,优雅地丢弃其中定义的主题项目。如果该类型为变种,则该信息也会被消除。如果该类型为类型变种的基础类型,则那些变种会失去其基础类型。
void rename_color(old_name: StringName, name: StringName, theme_type: StringName) 🔗
如果主题类型 theme_type
中存在名为 old_name
的 Color 属性,则将其重命名为 name
。
不存在时失败,新名称已存在时也会失败。请使用 has_color 检查是否存在,使用 clear_color 移除现有属性。
void rename_constant(old_name: StringName, name: StringName, theme_type: StringName) 🔗
如果主题类型 theme_type
中存在名为 old_name
的常量属性,则将其重命名为 name
。
不存在时失败,新名称已存在时也会失败。请使用 has_constant 检查是否存在,使用 clear_constant 移除现有属性。
void rename_font(old_name: StringName, name: StringName, theme_type: StringName) 🔗
如果主题类型 theme_type
中存在名为 old_name
的 Font 属性,则将其重命名为 name
。
不存在时失败,新名称已存在时也会失败。请使用 has_font 检查是否存在,使用 clear_font 移除现有属性。
void rename_font_size(old_name: StringName, name: StringName, theme_type: StringName) 🔗
如果主题类型 theme_type
中存在名为 old_name
的字体大小属性,则将其重命名为 name
。
不存在时失败,新名称已存在时也会失败。请使用 has_font_size 检查是否存在,使用 clear_font_size 移除现有属性。
void rename_icon(old_name: StringName, name: StringName, theme_type: StringName) 🔗
如果主题类型 theme_type
中存在名为 old_name
的图标属性,则将其重命名为 name
。
不存在时失败,新名称已存在时也会失败。请使用 has_icon 检查是否存在,使用 clear_icon 移除现有属性。
void rename_stylebox(old_name: StringName, name: StringName, theme_type: StringName) 🔗
如果主题类型 theme_type
中存在名为 old_name
的 StyleBox 属性,则将其重命名为 name
。
不存在时失败,新名称已存在时也会失败。请使用 has_stylebox 检查是否存在,使用 clear_stylebox 移除现有属性。
void rename_theme_item(data_type: DataType, old_name: StringName, name: StringName, theme_type: StringName) 🔗
如果主题类型 theme_type
中存在名为 old_name
的主题属性,则将其重命名为 name
。
不存在时失败,新名称已存在时也会失败。请使用 has_theme_item 检查是否存在,使用 clear_theme_item 移除现有属性。
注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。
void set_color(name: StringName, theme_type: StringName, color: Color) 🔗
创建或改变由名称 name
和主题类型 theme_type
定义的 Color 属性的值。移除该属性请使用 clear_color。
void set_constant(name: StringName, theme_type: StringName, constant: int) 🔗
创建或改变由名称 name
和主题类型 theme_type
定义的常量属性的值。移除该属性请使用 clear_constant。
void set_font(name: StringName, theme_type: StringName, font: Font) 🔗
创建或改变由名称 name
和主题类型 theme_type
定义的 Font 属性的值。移除该属性请使用 clear_font。
void set_font_size(name: StringName, theme_type: StringName, font_size: int) 🔗
创建或改变由名称 name
和主题类型 theme_type
定义的字体大小属性的值。移除该属性请使用 clear_font_size。
void set_icon(name: StringName, theme_type: StringName, texture: Texture2D) 🔗
创建或改变由名称 name
和主题类型 theme_type
定义的图标属性的值。移除该属性请使用 clear_icon。
void set_stylebox(name: StringName, theme_type: StringName, texture: StyleBox) 🔗
创建或改变由名称 name
和主题类型 theme_type
定义的 StyleBox 属性的值。移除该属性请使用 clear_stylebox。
void set_theme_item(data_type: DataType, name: StringName, theme_type: StringName, value: Variant) 🔗
创建或改变由名称 name
和主题类型 theme_type
定义的主题属性的值。移除该属性请使用 clear_theme_item。
如果 value
的类型不被 data_type
所接受,则失败。
注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。
void set_type_variation(theme_type: StringName, base_type: StringName) 🔗
将主题类型 theme_type
标记为基础类型 base_type
的变种。
这会将 theme_type
添加为属于 base_type
类的 Control 的 Control.theme_type_variation 的建议选项。
变种也可以嵌套,即 base_type
可以是另一个变种。如果变种链以匹配 Control 类的 base_type
结束,则整个链将被建议为选项。
注意:仅当该主题资源被设置为项目的默认主题时才会显示建议。参见 ProjectSettings.gui/theme/custom。