Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Theme

继承: Resource < RefCounted < Object

用于样式化/皮肤化 ControlWindow 的资源。

描述

用于样式化/皮肤化 ControlWindow 节点的资源。控件可以使用本地的主题覆盖项进行单独的风格化(见 Control.add_theme_color_override),而主题资源则能够存储这些设置,在所有同类型的控件之间实现共享(例如将所有 Button 都设置为相同的风格)。主题资源可以在整个项目上使用,但你也可以为单独的一个控件节点分支设置不同的主题资源。为某个控件节点分配的主题资源不仅会对它自己生效,也会对它的所有直接和间接子节点生效(只要控件链没有中断)。

项目范围的主题请使用 ProjectSettings.gui/theme/custom 设置,这样项目中的所有控件就都能够使用。

控件节点的主题请使用 Control.theme 设置,这样该控件和它的所有直接和间接子节点就都能够使用。

教程

属性

float

default_base_scale

0.0

Font

default_font

int

default_font_size

-1

方法

void

add_type ( StringName theme_type )

void

clear ( )

void

clear_color ( StringName name, StringName theme_type )

void

clear_constant ( StringName name, StringName theme_type )

void

clear_font ( StringName name, StringName theme_type )

void

clear_font_size ( StringName name, StringName theme_type )

void

clear_icon ( StringName name, StringName theme_type )

void

clear_stylebox ( StringName name, StringName theme_type )

void

clear_theme_item ( DataType data_type, StringName name, StringName theme_type )

void

clear_type_variation ( StringName theme_type )

Color

get_color ( StringName name, StringName theme_type ) const

PackedStringArray

get_color_list ( String theme_type ) const

PackedStringArray

get_color_type_list ( ) const

int

get_constant ( StringName name, StringName theme_type ) const

PackedStringArray

get_constant_list ( String theme_type ) const

PackedStringArray

get_constant_type_list ( ) const

Font

get_font ( StringName name, StringName theme_type ) const

PackedStringArray

get_font_list ( String theme_type ) const

int

get_font_size ( StringName name, StringName theme_type ) const

PackedStringArray

get_font_size_list ( String theme_type ) const

PackedStringArray

get_font_size_type_list ( ) const

PackedStringArray

get_font_type_list ( ) const

Texture2D

get_icon ( StringName name, StringName theme_type ) const

PackedStringArray

get_icon_list ( String theme_type ) const

PackedStringArray

get_icon_type_list ( ) const

StyleBox

get_stylebox ( StringName name, StringName theme_type ) const

PackedStringArray

get_stylebox_list ( String theme_type ) const

PackedStringArray

get_stylebox_type_list ( ) const

Variant

get_theme_item ( DataType data_type, StringName name, StringName theme_type ) const

PackedStringArray

get_theme_item_list ( DataType data_type, String theme_type ) const

PackedStringArray

get_theme_item_type_list ( DataType data_type ) const

PackedStringArray

get_type_list ( ) const

StringName

get_type_variation_base ( StringName theme_type ) const

PackedStringArray

get_type_variation_list ( StringName base_type ) const

bool

has_color ( StringName name, StringName theme_type ) const

bool

has_constant ( StringName name, StringName theme_type ) const

bool

has_default_base_scale ( ) const

bool

has_default_font ( ) const

bool

has_default_font_size ( ) const

bool

has_font ( StringName name, StringName theme_type ) const

bool

has_font_size ( StringName name, StringName theme_type ) const

bool

has_icon ( StringName name, StringName theme_type ) const

bool

has_stylebox ( StringName name, StringName theme_type ) const

bool

has_theme_item ( DataType data_type, StringName name, StringName theme_type ) const

bool

is_type_variation ( StringName theme_type, StringName base_type ) const

void

merge_with ( Theme other )

void

remove_type ( StringName theme_type )

void

rename_color ( StringName old_name, StringName name, StringName theme_type )

void

rename_constant ( StringName old_name, StringName name, StringName theme_type )

void

rename_font ( StringName old_name, StringName name, StringName theme_type )

void

rename_font_size ( StringName old_name, StringName name, StringName theme_type )

void

rename_icon ( StringName old_name, StringName name, StringName theme_type )

void

rename_stylebox ( StringName old_name, StringName name, StringName theme_type )

void

rename_theme_item ( DataType data_type, StringName old_name, StringName name, StringName theme_type )

void

set_color ( StringName name, StringName theme_type, Color color )

void

set_constant ( StringName name, StringName theme_type, int constant )

void

set_font ( StringName name, StringName theme_type, Font font )

void

set_font_size ( StringName name, StringName theme_type, int font_size )

void

set_icon ( StringName name, StringName theme_type, Texture2D texture )

void

set_stylebox ( StringName name, StringName theme_type, StyleBox texture )

void

set_theme_item ( DataType data_type, StringName name, StringName theme_type, Variant value )

void

set_type_variation ( StringName theme_type, StringName base_type )


枚举

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

  • void set_default_base_scale ( float value )

  • float get_default_base_scale ( )

该主题资源的默认基础缩放系数。部分控件会用它来根据全局缩放系数对其视觉属性进行缩放。如果该值为 0.0,则使用全局缩放系数(见 ThemeDB.fallback_base_scale)。

请使用 has_default_base_scale 来检查该值是否有效。


Font default_font

  • void set_default_font ( Font value )

  • Font get_default_font ( )

该主题资源的默认字体。尝试获取字体资源时,如果该主题中不存在或者为无效状态,则会用它作为默认值。如果默认字体也缺失或无效,则会使用引擎的回退值(见 ThemeDB.fallback_font)。

请使用 has_default_font 来检查该值是否有效。


int default_font_size = -1

  • void set_default_font_size ( int value )

  • int get_default_font_size ( )

该主题资源的默认字体大小。尝试获取字体大小时,如果该主题中不存在或者为无效状态,则会用它作为默认值。如果默认字体大小也缺失或无效,则会使用引擎的回退值(见 ThemeDB.fallback_font_size)。

小于 0 的值无效,可用于清除对该属性的设置。请使用 has_default_font_size 来检查该值是否有效。


方法说明

void add_type ( StringName theme_type )

为每一个有效的数据类型都添加一个空主题类型。

注意:空类型不会随该主题保存。这个方法的存在是为了对资源执行内存中的更改。请使用 set_* 方法添加主题项目。


void clear ( )

移除在该主题资源上定义的所有主题属性。


void clear_color ( StringName name, StringName theme_type )

如果存在由 nametheme_type 定义的 Color 属性,则将其移除。

如果不存在则失败。请使用 has_color 检查是否存在。


void clear_constant ( StringName name, StringName theme_type )

如果存在由 nametheme_type 定义的常量属性,则将其移除。

如果不存在则失败。请使用 has_constant 检查是否存在。


void clear_font ( StringName name, StringName theme_type )

如果存在由 nametheme_type 定义的 Font 属性,则将其移除。

如果不存在则失败。请使用 has_font 检查是否存在。


void clear_font_size ( StringName name, StringName theme_type )

如果存在由 nametheme_type 定义的字体大小属性,则将其移除。

如果不存在则失败。请使用 has_font_size 检查是否存在。


void clear_icon ( StringName name, StringName theme_type )

如果存在由 nametheme_type 定义的图标属性,则将其移除。

如果不存在则失败。请使用 has_icon 检查是否存在。


void clear_stylebox ( StringName name, StringName theme_type )

如果存在由 nametheme_type 定义的 StyleBox 属性,则将其移除。

如果不存在则失败。请使用 has_stylebox 检查是否存在。


void clear_theme_item ( DataType data_type, StringName name, StringName theme_type )

如果存在由 nametheme_type 定义的 data_type 属性,则将其移除。

如果不存在则失败。请使用 has_theme_item 检查是否存在。

注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。


void clear_type_variation ( StringName theme_type )

取消将主题类型 theme_type 标记为任何主题类型的变种。见 set_type_variation


Color get_color ( StringName name, StringName theme_type ) const

如果存在由 nametheme_type 定义的 Color 属性,则将其返回。

如果不存在则返回默认颜色。请使用 has_color 检查是否存在。


PackedStringArray get_color_list ( String theme_type ) const

返回为 theme_type 类型定义的 Color 属性的名称列表。请使用 get_color_type_list 获取可能的主题类型名称。


PackedStringArray get_color_type_list ( ) const

返回 Color 属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。


int get_constant ( StringName name, StringName theme_type ) const

如果存在由 nametheme_type 定义的常量属性,则将其返回。

如果不存在则返回 0。请使用 has_constant 检查是否存在。


PackedStringArray get_constant_list ( String theme_type ) const

返回为 theme_type 类型定义的常量属性的名称列表。请使用 get_constant_type_list 获取可能的主题类型名称。


PackedStringArray get_constant_type_list ( ) const

返回常量属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。


Font get_font ( StringName name, StringName theme_type ) const

如果存在由 nametheme_type 定义的 Font 属性,则将其返回。

如果不存在且存在默认主题字体,则返回默认主题字体(见 default_font)。请使用 has_font 检查是否存在,使用 has_default_font 检查默认主题字体是否存在。

如果两者都不存在,则返回引擎的回退字体值(见 ThemeDB.fallback_font)。


PackedStringArray get_font_list ( String theme_type ) const

返回为 theme_type 类型定义的 Font 属性的名称列表。请使用 get_font_type_list 获取可能的主题类型名称。


int get_font_size ( StringName name, StringName theme_type ) const

如果存在由 nametheme_type 定义的字体大小属性,则将其返回。

如果不存在且存在默认主题字体大小,则返回默认主题字体大小(见 default_font_size)。请使用 has_font_size 检查是否存在,使用 has_default_font_size 检查默认主题字体大小是否存在。

如果两者都不存在,则返回引擎的回退字体大小值(见 ThemeDB.fallback_font_size)。


PackedStringArray get_font_size_list ( String theme_type ) 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 ( StringName name, StringName theme_type ) const

如果存在由 nametheme_type 定义的图标属性,则将其返回。

如果不存在则返回引擎的回退图标值(见 ThemeDB.fallback_icon)。请使用 has_icon 检查是否存在。


PackedStringArray get_icon_list ( String theme_type ) const

返回为 theme_type 类型定义的图标属性的名称列表。请使用 get_icon_type_list 获取可能的主题类型名称。


PackedStringArray get_icon_type_list ( ) const

返回图标属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。


StyleBox get_stylebox ( StringName name, StringName theme_type ) const

如果存在由 nametheme_type 定义的 StyleBox 属性,则将其返回。

如果不存在则返回引擎的回退样式盒值(见 ThemeDB.fallback_stylebox)。请使用 has_stylebox 检查是否存在。


PackedStringArray get_stylebox_list ( String theme_type ) const

返回为 theme_type 类型定义的 StyleBox 属性的名称列表。请使用 get_stylebox_type_list 获取可能的主题类型名称。


PackedStringArray get_stylebox_type_list ( ) const

返回 StyleBox 属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。


Variant get_theme_item ( DataType data_type, StringName name, StringName theme_type ) const

如果存在由 nametheme_type 定义的 data_type 属性,则将其返回。

如果不存在则返回引擎的回退值(见 ThemeDB)。请使用 has_theme_item 检查是否存在。

注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。


PackedStringArray get_theme_item_list ( DataType data_type, String theme_type ) const

返回为 theme_type 类型定义的 data_type 属性的名称列表。请使用 get_theme_item_type_list 获取可能的主题类型名称。

注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。


PackedStringArray get_theme_item_type_list ( DataType data_type ) const

返回 data_type 属性的所有唯一主题类型名称的列表。请使用 get_type_list 获取所有主题类型。

注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。


PackedStringArray get_type_list ( ) const

返回所有唯一主题类型名称的列表。获取单一数据类型的唯一主题类型列表请使用对应的 get_*_type_list 方法。


StringName get_type_variation_base ( StringName theme_type ) const

如果 theme_type 是有效的变种类型,则返回其基础主题类型的名称。否则返回空字符串。


PackedStringArray get_type_variation_list ( StringName base_type ) const

返回给定基础类型 base_type 的所有类型变种列表。


bool has_color ( StringName name, StringName theme_type ) const

如果主题类型 theme_type 中存在名为 nameColor 属性,则返回 true

不存在时返回 false。定义请使用 set_color


bool has_constant ( StringName name, StringName theme_type ) 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 ( StringName name, StringName theme_type ) const

如果主题类型 theme_type 中存在名为 nameFont 属性,则返回 true

不存在时返回 false。定义请使用 set_font


bool has_font_size ( StringName name, StringName theme_type ) const

如果主题类型 theme_type 中存在名为 name 的字体大小属性,则返回 true

不存在时返回 false。定义请使用 set_font_size


bool has_icon ( StringName name, StringName theme_type ) const

如果主题类型 theme_type 中存在名为 name 的图标属性,则返回 true

不存在时返回 false。定义请使用 set_icon


bool has_stylebox ( StringName name, StringName theme_type ) const

如果主题类型 theme_type 中存在名为 nameStyleBox 属性,则返回 true

不存在时返回 false。定义请使用 set_stylebox


bool has_theme_item ( DataType data_type, StringName name, StringName theme_type ) const

如果主题类型 theme_type 中存在名为 name 的主题属性,则返回 true

不存在时返回 false。定义请使用 set_theme_item

注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。


bool is_type_variation ( StringName theme_type, StringName base_type ) const

如果主题类型 theme_type 被标记为基础类型 base_type 的变种,则返回 true


void merge_with ( Theme other )

添加缺失的定义,并使用 other 主题资源中的值覆盖已有的定义。

注意:这修改了当前的主题。如果想将两个主题合并在一起且不修改任何一个,请创建一个新的空主题,并将其他两个依次合并到其中。


void remove_type ( StringName theme_type )

移除该主题类型,优雅地丢弃其中定义的主题项目。如果该类型为变种,则该信息也会被消除。如果该类型为类型变种的基础类型,则那些变种会失去其基础类型。


void rename_color ( StringName old_name, StringName name, StringName theme_type )

如果主题类型 theme_type 中存在名为 old_nameColor 属性,则将其重命名为 name

不存在时失败,新名称已存在时也会失败。请使用 has_color 检查是否存在,使用 clear_color 移除现有属性。


void rename_constant ( StringName old_name, StringName name, StringName theme_type )

如果主题类型 theme_type 中存在名为 old_name 的常量属性,则将其重命名为 name

不存在时失败,新名称已存在时也会失败。请使用 has_constant 检查是否存在,使用 clear_constant 移除现有属性。


void rename_font ( StringName old_name, StringName name, StringName theme_type )

如果主题类型 theme_type 中存在名为 old_nameFont 属性,则将其重命名为 name

不存在时失败,新名称已存在时也会失败。请使用 has_font 检查是否存在,使用 clear_font 移除现有属性。


void rename_font_size ( StringName old_name, StringName name, StringName theme_type )

如果主题类型 theme_type 中存在名为 old_name 的字体大小属性,则将其重命名为 name

不存在时失败,新名称已存在时也会失败。请使用 has_font_size 检查是否存在,使用 clear_font_size 移除现有属性。


void rename_icon ( StringName old_name, StringName name, StringName theme_type )

如果主题类型 theme_type 中存在名为 old_name 的图标属性,则将其重命名为 name

不存在时失败,新名称已存在时也会失败。请使用 has_icon 检查是否存在,使用 clear_icon 移除现有属性。


void rename_stylebox ( StringName old_name, StringName name, StringName theme_type )

如果主题类型 theme_type 中存在名为 old_nameStyleBox 属性,则将其重命名为 name

不存在时失败,新名称已存在时也会失败。请使用 has_stylebox 检查是否存在,使用 clear_stylebox 移除现有属性。


void rename_theme_item ( DataType data_type, StringName old_name, StringName name, StringName theme_type )

如果主题类型 theme_type 中存在名为 old_name 的主题属性,则将其重命名为 name

不存在时失败,新名称已存在时也会失败。请使用 has_theme_item 检查是否存在,使用 clear_theme_item 移除现有属性。

注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。


void set_color ( StringName name, StringName theme_type, Color color )

创建或改变由名称 name 和主题类型 theme_type 定义的 Color 属性的值。移除该属性请使用 clear_color


void set_constant ( StringName name, StringName theme_type, int constant )

创建或改变由名称 name 和主题类型 theme_type 定义的常量属性的值。移除该属性请使用 clear_constant


void set_font ( StringName name, StringName theme_type, Font font )

创建或改变由名称 name 和主题类型 theme_type 定义的 Font 属性的值。移除该属性请使用 clear_font


void set_font_size ( StringName name, StringName theme_type, int font_size )

创建或改变由名称 name 和主题类型 theme_type 定义的字体大小属性的值。移除该属性请使用 clear_font_size


void set_icon ( StringName name, StringName theme_type, Texture2D texture )

创建或改变由名称 name 和主题类型 theme_type 定义的图标属性的值。移除该属性请使用 clear_icon


void set_stylebox ( StringName name, StringName theme_type, StyleBox texture )

创建或改变由名称 name 和主题类型 theme_type 定义的 StyleBox 属性的值。移除该属性请使用 clear_stylebox


void set_theme_item ( DataType data_type, StringName name, StringName theme_type, Variant value )

创建或改变由名称 name 和主题类型 theme_type 定义的主题属性的值。移除该属性请使用 clear_theme_item

如果 value 的类型不被 data_type 所接受,则失败。

注意:这个方法类似于调用相应的数据类型特定方法,但可以用于更通用逻辑。


void set_type_variation ( StringName theme_type, StringName base_type )

将主题类型 theme_type 标记为基础类型 base_type 的变种。

这会将 theme_type 添加为属于 base_type 类的 ControlControl.theme_type_variation 的建议选项。

变种也可以嵌套,即 base_type 可以是另一个变种。如果变种链以匹配 Control 类的 base_type 结束,则整个链将被建议为选项。

注意:仅当该主题资源被设置为项目的默认主题时才会显示建议。参见 ProjectSettings.gui/theme/custom