Up to date

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

Control

继承: CanvasItem < Node < Object

派生: BaseButton, ColorRect, Container, GraphEdit, ItemList, Label, LineEdit, MenuBar, NinePatchRect, Panel, Range, ReferenceRect, RichTextLabel, Separator, TabBar, TextEdit, TextureRect, Tree, VideoStreamPlayer

所有 GUI 控件的基类。根据其父控件调整其位置和大小。

描述

所有 UI 相关节点的基类。Control 具有定义其范围的边界矩形,相对于父控件或当前视口的锚点位置,以及相对于锚点的偏移。当节点、任何父节点或屏幕尺寸发生变化时,偏移就会自动更新。

更多关于 Godot 的 UI 系统、锚点、偏移和容器的信息,请参阅手册中的相关教程。要构建灵活的 UI,你需要混合使用从 ControlContainer 节点继承的 UI 元素。

用户界面节点与输入

Godot 使用视口来传播输入事件。视口负责将 InputEvent 传播给它的子节点。因为 SceneTree.rootWindow,所以游戏中的所有 UI 元素都会自动进行传播。

输入事件通过调用 Node._inputSceneTree 中传播,从根节点传播到所有子节点。对 UI 元素而言,覆盖的最好是 _gui_input,可以过滤掉无关的输入事件,例如它会对 Z 顺序、mouse_filter、焦点、事件是否在该控件的边界框内等条件进行检查。

请调用 accept_event,这样其他节点就不会收到该事件。输入被接受后,就会被标记为已处理,Node._unhandled_input 不会对它进行处理。

只能有一个 Control 节点处于焦点。只有处于焦点的节点才会接收到事件。要获得焦点,请调用 grab_focus。导致 Control 节点失去焦点的情况有:其他节点获得了焦点、隐藏了聚焦节点。

mouse_filter 设置为 MOUSE_FILTER_IGNORE 可以让 Control 节点忽略鼠标或触摸事件。如果你在按钮上放了一个图标,就会需要用到。

Theme 资源会更改控件的外观。如果你更改了 Control 节点上的 Theme,则会影响其所有子节点。要覆盖某些主题的参数,请调用 add_theme_*_override 方法,例如 add_theme_font_override。你可以使用检查器覆盖主题。

注意:主题项不是 Object 的属性。这意味着你无法使用 Object.getObject.set 访问它们的值。请改用这个类的 get_theme_*add_theme_*_override 方法。

教程

属性

float

anchor_bottom

0.0

float

anchor_left

0.0

float

anchor_right

0.0

float

anchor_top

0.0

bool

auto_translate

true

bool

clip_contents

false

Vector2

custom_minimum_size

Vector2(0, 0)

FocusMode

focus_mode

0

NodePath

focus_neighbor_bottom

NodePath("")

NodePath

focus_neighbor_left

NodePath("")

NodePath

focus_neighbor_right

NodePath("")

NodePath

focus_neighbor_top

NodePath("")

NodePath

focus_next

NodePath("")

NodePath

focus_previous

NodePath("")

Vector2

global_position

GrowDirection

grow_horizontal

1

GrowDirection

grow_vertical

1

LayoutDirection

layout_direction

0

bool

localize_numeral_system

true

CursorShape

mouse_default_cursor_shape

0

MouseFilter

mouse_filter

0

bool

mouse_force_pass_scroll_events

true

float

offset_bottom

0.0

float

offset_left

0.0

float

offset_right

0.0

float

offset_top

0.0

Vector2

pivot_offset

Vector2(0, 0)

Vector2

position

Vector2(0, 0)

float

rotation

0.0

float

rotation_degrees

Vector2

scale

Vector2(1, 1)

Node

shortcut_context

Vector2

size

Vector2(0, 0)

BitField<SizeFlags>

size_flags_horizontal

1

float

size_flags_stretch_ratio

1.0

BitField<SizeFlags>

size_flags_vertical

1

Theme

theme

StringName

theme_type_variation

&""

String

tooltip_text

""

方法

bool

_can_drop_data ( Vector2 at_position, Variant data ) virtual const

void

_drop_data ( Vector2 at_position, Variant data ) virtual

Variant

_get_drag_data ( Vector2 at_position ) virtual

Vector2

_get_minimum_size ( ) virtual const

String

_get_tooltip ( Vector2 at_position ) virtual const

void

_gui_input ( InputEvent event ) virtual

bool

_has_point ( Vector2 point ) virtual const

Object

_make_custom_tooltip ( String for_text ) virtual const

Vector3i[]

_structured_text_parser ( Array args, String text ) virtual const

void

accept_event ( )

void

add_theme_color_override ( StringName name, Color color )

void

add_theme_constant_override ( StringName name, int constant )

void

add_theme_font_override ( StringName name, Font font )

void

add_theme_font_size_override ( StringName name, int font_size )

void

add_theme_icon_override ( StringName name, Texture2D texture )

void

add_theme_stylebox_override ( StringName name, StyleBox stylebox )

void

begin_bulk_theme_override ( )

void

end_bulk_theme_override ( )

Control

find_next_valid_focus ( ) const

Control

find_prev_valid_focus ( ) const

Control

find_valid_focus_neighbor ( Side side ) const

void

force_drag ( Variant data, Control preview )

float

get_anchor ( Side side ) const

Vector2

get_begin ( ) const

Vector2

get_combined_minimum_size ( ) const

CursorShape

get_cursor_shape ( Vector2 position=Vector2(0, 0) ) const

Vector2

get_end ( ) const

NodePath

get_focus_neighbor ( Side side ) const

Rect2

get_global_rect ( ) const

Vector2

get_minimum_size ( ) const

float

get_offset ( Side offset ) const

Vector2

get_parent_area_size ( ) const

Control

get_parent_control ( ) const

Rect2

get_rect ( ) const

Vector2

get_screen_position ( ) const

Color

get_theme_color ( StringName name, StringName theme_type="" ) const

int

get_theme_constant ( StringName name, StringName theme_type="" ) const

float

get_theme_default_base_scale ( ) const

Font

get_theme_default_font ( ) const

int

get_theme_default_font_size ( ) const

Font

get_theme_font ( StringName name, StringName theme_type="" ) const

int

get_theme_font_size ( StringName name, StringName theme_type="" ) const

Texture2D

get_theme_icon ( StringName name, StringName theme_type="" ) const

StyleBox

get_theme_stylebox ( StringName name, StringName theme_type="" ) const

String

get_tooltip ( Vector2 at_position=Vector2(0, 0) ) const

void

grab_click_focus ( )

void

grab_focus ( )

bool

has_focus ( ) const

bool

has_theme_color ( StringName name, StringName theme_type="" ) const

bool

has_theme_color_override ( StringName name ) const

bool

has_theme_constant ( StringName name, StringName theme_type="" ) const

bool

has_theme_constant_override ( StringName name ) const

bool

has_theme_font ( StringName name, StringName theme_type="" ) const

bool

has_theme_font_override ( StringName name ) const

bool

has_theme_font_size ( StringName name, StringName theme_type="" ) const

bool

has_theme_font_size_override ( StringName name ) const

bool

has_theme_icon ( StringName name, StringName theme_type="" ) const

bool

has_theme_icon_override ( StringName name ) const

bool

has_theme_stylebox ( StringName name, StringName theme_type="" ) const

bool

has_theme_stylebox_override ( StringName name ) const

bool

is_drag_successful ( ) const

bool

is_layout_rtl ( ) const

void

release_focus ( )

void

remove_theme_color_override ( StringName name )

void

remove_theme_constant_override ( StringName name )

void

remove_theme_font_override ( StringName name )

void

remove_theme_font_size_override ( StringName name )

void

remove_theme_icon_override ( StringName name )

void

remove_theme_stylebox_override ( StringName name )

void

reset_size ( )

void

set_anchor ( Side side, float anchor, bool keep_offset=false, bool push_opposite_anchor=true )

void

set_anchor_and_offset ( Side side, float anchor, float offset, bool push_opposite_anchor=false )

void

set_anchors_and_offsets_preset ( LayoutPreset preset, LayoutPresetMode resize_mode=0, int margin=0 )

void

set_anchors_preset ( LayoutPreset preset, bool keep_offsets=false )

void

set_begin ( Vector2 position )

void

set_drag_forwarding ( Callable drag_func, Callable can_drop_func, Callable drop_func )

void

set_drag_preview ( Control control )

void

set_end ( Vector2 position )

void

set_focus_neighbor ( Side side, NodePath neighbor )

void

set_global_position ( Vector2 position, bool keep_offsets=false )

void

set_offset ( Side side, float offset )

void

set_offsets_preset ( LayoutPreset preset, LayoutPresetMode resize_mode=0, int margin=0 )

void

set_position ( Vector2 position, bool keep_offsets=false )

void

set_size ( Vector2 size, bool keep_offsets=false )

void

update_minimum_size ( )

void

warp_mouse ( Vector2 position )


信号

focus_entered ( )

当该节点获得焦点时发出。


focus_exited ( )

当该节点失去焦点时发出。


gui_input ( InputEvent event )

当节点收到 InputEvent 时发出。


minimum_size_changed ( )

当节点的最小大小更改时发出。


mouse_entered ( )

当鼠标光标进入控件(或任何子控件)的可见区域时发出,可见区域即未被其他 Control 和 Window 遮挡的区域,需要 mouse_filter 允许事件达到,与控件是否持有焦点无关。

注意:CanvasItem.z_index 不影响哪个 Control 会收到信号。


mouse_exited ( )

当鼠标光标离开控件(或任何子控件)的可见区域时发出,可见区域即未被其他 Control 和 Window 遮挡的区域,需要 mouse_filter 允许事件达到,与控件是否持有焦点无关。

注意:CanvasItem.z_index 不影响哪个 Control 会收到信号。

注意:如果要忽略任何顶部节点,检查鼠标是否真的离开了该区域,可以使用如下代码:

func _on_mouse_exited():
    if not Rect2(Vector2(), size).has_point(get_local_mouse_position()):
        # 未悬停在区域上。

resized ( )

当控件更改大小时发出。


size_flags_changed ( )

当大小标志之一更改时发出。见 size_flags_horizontalsize_flags_vertical


theme_changed ( )

发送 NOTIFICATION_THEME_CHANGED 通知时发出。


枚举

enum FocusMode:

FocusMode FOCUS_NONE = 0

该节点无法获取焦点。在 focus_mode 中使用。

FocusMode FOCUS_CLICK = 1

该节点只能通过鼠标点击获取焦点。在 focus_mode 中使用。

FocusMode FOCUS_ALL = 2

该节点可以通过鼠标单击、使用键盘上的箭头和 Tab 键、或使用游戏手柄上的方向键来获取焦点。用于 focus_mode


enum CursorShape:

CursorShape CURSOR_ARROW = 0

当用户将节点悬停时,显示系统的箭头鼠标光标。与 mouse_default_cursor_shape 成员一起使用。

CursorShape CURSOR_IBEAM = 1

当用户将节点悬停时,显示系统的 I 型光束鼠标光标。工字梁指针的形状类似于“I”。它告诉用户他们可以突出显示或插入文本。

CursorShape CURSOR_POINTING_HAND = 2

当用户将节点悬停时,显示系统的手形鼠标光标。

CursorShape CURSOR_CROSS = 3

当用户将鼠标悬停在节点上时,显示系统的交叉鼠标光标。

CursorShape CURSOR_WAIT = 4

当用户悬停节点时,显示系统等待的鼠标光标。通常是一个沙漏。

CursorShape CURSOR_BUSY = 5

当用户悬停节点时,显示系统繁忙的鼠标光标。通常是箭头加一个小沙漏。

CursorShape CURSOR_DRAG = 6

当用户悬停在节点上时,显示系统的拖动鼠标光标,通常是一个闭合的拳头或十字符号。它告诉用户他们当前正在拖动一个项目,例如场景面板中的节点。

CursorShape CURSOR_CAN_DROP = 7

当用户悬停节点时,显示系统的落地鼠标光标。它可以是一个张开的手。它告诉用户可以放下一个他们当前正在抓取的物品,比如场景面板中的一个节点。

CursorShape CURSOR_FORBIDDEN = 8

当用户悬停节点时,显示系统禁止的鼠标光标。通常是一个交叉的圆圈。

CursorShape CURSOR_VSIZE = 9

当用户悬停节点时,显示系统的垂直调整鼠标光标。一个双头的垂直箭头。它告诉用户可以垂直调整窗口或面板的大小。

CursorShape CURSOR_HSIZE = 10

当用户悬停节点时,显示系统的水平调整鼠标光标。一个双头的水平箭头。它告诉用户可以水平调整窗口或面板的大小。

CursorShape CURSOR_BDIAGSIZE = 11

当用户将节点悬停时,显示系统窗口调整大小的鼠标光标。光标是从左下角到右上角的双向箭头。它告诉用户可以水平和垂直调整窗口或面板的大小。

CursorShape CURSOR_FDIAGSIZE = 12

当用户将节点悬停时,显示系统窗口调整大小的鼠标光标。光标是一个双向箭头,从左上角到右下角,与 CURSOR_BDIAGSIZE 相反。它告诉用户可以水平和垂直调整窗口或面板的大小。

CursorShape CURSOR_MOVE = 13

当用户将节点悬停时,显示系统的移动鼠标光标。它以 90 度角显示 2 个双向箭头。它告诉用户他们可以自由移动 UI 元素。

CursorShape CURSOR_VSPLIT = 14

当用户将节点悬停时,显示系统的垂直拆分鼠标光标。在 Windows 上与 CURSOR_VSIZE 相同。

CursorShape CURSOR_HSPLIT = 15

当用户将节点悬停时,显示系统的水平拆分鼠标光标。在 Windows 上与 CURSOR_HSIZE 相同。

CursorShape CURSOR_HELP = 16

当用户将节点悬停在一个节点上时,显示系统的帮助鼠标光标,一个问号。


enum LayoutPreset:

LayoutPreset PRESET_TOP_LEFT = 0

将所有 4 个锚点对齐到父控件边界的左上角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_TOP_RIGHT = 1

将所有 4 个锚点对齐到父控件边界的右上角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_BOTTOM_LEFT = 2

将所有 4 个锚点对齐到父控件边界的左下角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_BOTTOM_RIGHT = 3

将所有 4 个锚点对齐到父控件边界的右下角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_CENTER_LEFT = 4

将所有 4 个锚点对齐到父控件边界的左边缘的中点。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_CENTER_TOP = 5

将所有 4 个锚点对齐到父控件边界的顶边缘的中点。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_CENTER_RIGHT = 6

将所有 4 个锚点对齐到父控件边界的右边缘的中点。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_CENTER_BOTTOM = 7

将所有 4 个锚点对齐到父控件边界的底边缘的中点。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_CENTER = 8

将所有 4 个锚点对齐到父控件边界的中心。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_LEFT_WIDE = 9

将所有 4 个锚点对齐到父控件的左边缘。左偏移量相对于父节点的左边缘,上偏移量相对于父节点的左上角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_TOP_WIDE = 10

将所有 4 个锚点对齐到父控件的上边缘。左偏移量相对于父节点的左上角,上偏移量相对于父节点的上边缘,右偏移相对于父节点的右上角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_RIGHT_WIDE = 11

将所有 4 个锚点对齐到父控件的右边缘。右偏移量相对于父节点的右边缘,上偏移量相对于父节点的右上角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_BOTTOM_WIDE = 12

将所有 4 个锚点对齐到父控件的下边缘。左偏移量相对于父节点的左下角,下偏移量相对于父节点的下边缘,右偏移相对于父节点的右下角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_VCENTER_WIDE = 13

将所有 4 个锚点对齐到一条垂直线,该垂直线将父控件切成两半。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_HCENTER_WIDE = 14

将所有 4 个锚点对齐到一条水平线,该水平线将父控件切成两半。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_FULL_RECT = 15

将所有 4 个锚点对齐到父控件对应的角。应用此预设后,会将所有 4 个偏移都设置为 0,该 Control 将适合其父控件。与 set_anchors_preset 一起使用。


enum LayoutPresetMode:

LayoutPresetMode PRESET_MODE_MINSIZE = 0

控件将被调整为最小尺寸。

LayoutPresetMode PRESET_MODE_KEEP_WIDTH = 1

控件的宽度不会改变。

LayoutPresetMode PRESET_MODE_KEEP_HEIGHT = 2

控件的高度不会改变。

LayoutPresetMode PRESET_MODE_KEEP_SIZE = 3

控件的大小不会改变。


flags SizeFlags:

SizeFlags SIZE_SHRINK_BEGIN = 0

告诉父级 Container 将该节点与其起点对齐,即顶部或左侧。它与 SIZE_FILL 以及其他收缩大小标志互斥,但可以在某些容器中与 SIZE_EXPAND 一起使用。与 size_flags_horizontalsize_flags_vertical 一起使用。

注意:设置这个标志相当于没有任何大小标志。

SizeFlags SIZE_FILL = 1

告诉父级 Container 扩展该节点的边界以填充所有可用空间,而无需推动任何其他节点。它与收缩大小标志互斥。与 size_flags_horizontalsize_flags_vertical 一起使用。

SizeFlags SIZE_EXPAND = 2

告诉父级 Container 让该节点占用你标记的轴上的所有可用空间。如果将多个相邻节点设置为扩展,它们将根据其拉伸比共享空间。见 size_flags_stretch_ratio。用于 size_flags_horizontalsize_flags_vertical

SizeFlags SIZE_EXPAND_FILL = 3

将该节点的大小标志设置为填充和扩展。有关详细信息,请参阅 SIZE_FILLSIZE_EXPAND

SizeFlags SIZE_SHRINK_CENTER = 4

告诉父级 Container 将节点置于可用空间的中心。它与 SIZE_FILL 以及其他收缩大小标志互斥,但可以在某些容器中与 SIZE_EXPAND 一起使用。与 size_flags_horizontalsize_flags_vertical 一起使用。

SizeFlags SIZE_SHRINK_END = 8

告诉父级 Container 将节点与其末端对齐,即底部或右侧。它与 SIZE_FILL 以及其他收缩大小标志互斥,但可以在某些容器中与 SIZE_EXPAND 一起使用。与 size_flags_horizontalsize_flags_vertical 一起使用。


enum MouseFilter:

MouseFilter MOUSE_FILTER_STOP = 0

在控件上点击时,将通过 _gui_input 收到鼠标移动输入事件和鼠标按钮输入事件。控件能够接收到 mouse_enteredmouse_exited 信号。这些事件将自动被标记为已处理,不会进一步传播到其他控件。这也会导致其他控件中的信号被阻止。

MouseFilter MOUSE_FILTER_PASS = 1

在控件上点击时,将通过 _gui_input 收到鼠标移动输入事件和鼠标按钮输入事件。并且控件能够接收到 mouse_enteredmouse_exited 信号。如果此控件不处理事件,则将考虑其父控件(如果有的话),依此类推,直到没有更多的父控件可以处理该事件。这也允许信号在其他控件中触发。如果没有控件处理它,该事件将被传递到 Node._shortcut_input 进行进一步处理。

MouseFilter MOUSE_FILTER_IGNORE = 2

在控件上点击时,不会通过 _gui_input 收到鼠标移动输入事件和鼠标按钮输入事件,也不会接收到 mouse_enteredmouse_exited 信号。这不会阻止其他控件接收这些事件或触发信号。被忽略的事件将不会被自动处理。

注意:如果控件已收到 mouse_entered 但未收到 mouse_exited,则将 mouse_filter 更改为 MOUSE_FILTER_IGNORE 将导致发出 mouse_exited


enum GrowDirection:

GrowDirection GROW_DIRECTION_BEGIN = 0

如果控件的最小尺寸更改为大于其相应轴上的当前尺寸,则控件将向左或顶部增大以进行组合。

GrowDirection GROW_DIRECTION_END = 1

如果控件的最小尺寸更改为大于其相应轴上的当前尺寸,则控件将向右或向下增大以进行补偿。

GrowDirection GROW_DIRECTION_BOTH = 2

如果控件的最小大小更改为大于其当前大小,则控件将在两个方向上均等地增长以组成该控件。


enum Anchor:

Anchor ANCHOR_BEGIN = 0

将 4 个锚点的某一侧吸附到节点的 Rect 的左上角。在 anchor_* 成员变量中使用,例如 anchor_left。要一次更改全部 4 个锚点,请使用 set_anchors_preset

Anchor ANCHOR_END = 1

将 4 个锚点的某一侧吸附到节点的 Rect 的右下角。在 anchor_* 成员变量中使用,例如 anchor_left。要一次更改全部 4 个锚点,请使用 set_anchors_preset


enum LayoutDirection:

LayoutDirection LAYOUT_DIRECTION_INHERITED = 0

自动布局方向,由父控件布局方向决定。

LayoutDirection LAYOUT_DIRECTION_LOCALE = 1

自动布局方向,根据当前语言环境确定。

LayoutDirection LAYOUT_DIRECTION_LTR = 2

从左至右的布局方向。

LayoutDirection LAYOUT_DIRECTION_RTL = 3

从右至左的布局方向。


enum TextDirection:

TextDirection TEXT_DIRECTION_INHERITED = 3

文字书写方向与布局方向相同。

TextDirection TEXT_DIRECTION_AUTO = 0

自动文本书写方向,根据当前区域设置和文本内容确定。

TextDirection TEXT_DIRECTION_LTR = 1

从左至右的文本书写方向。

TextDirection TEXT_DIRECTION_RTL = 2

从右至左的文本书写方向。


常量

NOTIFICATION_RESIZED = 40

当节点改变大小时发送。请使用 size 获取新大小。

NOTIFICATION_MOUSE_ENTER = 41

当鼠标光标进入控件(或任何子控件)的可见区域时发送,可见区域即未被其他 Control 和 Window 遮挡的区域,需要 mouse_filter 允许事件达到,与控件是否持有焦点无关。

注意:CanvasItem.z_index 不影响哪个 Control 会收到该通知。

另见 NOTIFICATION_MOUSE_ENTER_SELF

NOTIFICATION_MOUSE_EXIT = 42

当鼠标光标离开控件(以及所有子控件)的可见区域时发送,可见区域即未被其他 Control 和 Window 遮挡的区域,需要 mouse_filter 允许事件达到,与控件是否持有焦点无关。

注意:CanvasItem.z_index 不影响哪个 Control 会收到该通知。

另见 NOTIFICATION_MOUSE_EXIT_SELF

NOTIFICATION_MOUSE_ENTER_SELF = 60

当鼠标光标进入控件的可见区域时发送,可见区域即未被其他 Control 和 Window 遮挡的区域,需要 mouse_filter 允许事件达到,与控件是否持有焦点无关。

注意:CanvasItem.z_index 不影响哪个 Control 会收到该通知。

另见 NOTIFICATION_MOUSE_ENTER

NOTIFICATION_MOUSE_EXIT_SELF = 61

当鼠标光标离开控件的可见区域时发送,可见区域即未被其他 Control 和 Window 遮挡的区域,需要 mouse_filter 允许事件达到,与控件是否持有焦点无关。

注意:CanvasItem.z_index 不影响哪个 Control 会收到该通知。

另见 NOTIFICATION_MOUSE_EXIT

NOTIFICATION_FOCUS_ENTER = 43

当节点获得焦点时发送。

NOTIFICATION_FOCUS_EXIT = 44

当节点失去焦点时发送。

NOTIFICATION_THEME_CHANGED = 45

当节点需要刷新其主题项目时发送。这发生在以下情况之一:

  • 在该节点或其任何祖先节点上的 theme 属性被更改。

  • 该节点上的 theme_type_variation 属性被更改。

  • 该节点的一个主题属性覆盖被更改。

  • 该节点进入场景树。

注意:作为一种优化,当该节点在场景树之外时,发生的更改不会发送该通知。相反,所有的主题项更新可以在该节点进入场景树时一次性应用。

NOTIFICATION_SCROLL_BEGIN = 47

当该节点位于 ScrollContainer 内部时发送,该容器在通过触摸事件拖动该可滚动区域时已开始滚动。通过拖动滚动条滚动、使用鼠标滚轮滚动、或使用键盘/游戏手柄事件滚动时,会发送该通知。

注意:该信号仅在在 Android 或 iOS 上、或当启用 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse 时的桌面/Web 平台上发出。

NOTIFICATION_SCROLL_END = 48

当该节点位于 ScrollContainer 内部时发送,该容器在通过触摸事件拖动该可滚动区域时已停止滚动。通过拖动滚动条滚动、使用鼠标滚轮滚动、或使用键盘/游戏手柄事件滚动时,会发送该通知。

注意:该信号仅在在 Android 或 iOS 上、或当启用 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse 时的桌面/Web 平台上发出。

NOTIFICATION_LAYOUT_DIRECTION_CHANGED = 49

当控件的布局方向改变时发送。


属性说明

float anchor_bottom = 0.0

将节点的底部边缘锚定到父控件的原点、中心或末端。会改变该节点发生移动或改变大小时底部偏移量的更新方式。方便起见,你可以使用 Anchor 常量。


float anchor_left = 0.0

将节点的左侧边缘锚定到父控件的原点、中心或末端。会改变该节点发生移动或改变大小时左侧偏移量的更新方式。方便起见,你可以使用 Anchor 常量。


float anchor_right = 0.0

将节点的右侧边缘锚定到父控件的原点、中心或末端。会改变该节点发生移动或改变大小时右侧偏移量的更新方式。方便起见,你可以使用 Anchor 常量。


float anchor_top = 0.0

将节点的顶部边缘锚定到父控件的原点、中心或末端。会改变该节点发生移动或改变大小时顶部偏移量的更新方式。方便起见,你可以使用 Anchor 常量。


bool auto_translate = true

  • void set_auto_translate ( bool value )

  • bool is_auto_translating ( )

切换是否所有文本都应该根据当前区域设置自动变为翻译后的版本。

还会决定生成 POT 时是否应解析该节点中的字符串。


bool clip_contents = false

  • void set_clip_contents ( bool value )

  • bool is_clipping_contents ( )

渲染基于 CanvasItem 的子节点时,是否应剪裁到该控件的矩形中。如果为 true,则子节点显示在该控件的矩形范围之外的部分,不会渲染,也不会接收输入。


Vector2 custom_minimum_size = Vector2(0, 0)

  • void set_custom_minimum_size ( Vector2 value )

  • Vector2 get_custom_minimum_size ( )

节点的边界矩形的最小尺寸。如果你将它设置为大于 (0,0) 的值,节点的边界矩形将始终至少有这个大小,即使它的内容更小。如果设置为 (0,0),节点的大小会自动适应其内容,无论是纹理还是子节点。


FocusMode focus_mode = 0

该控件的焦点访问模式(“无”“单击”或“全部”)。只能同时聚焦一个控件,该控件会收到键盘、手柄以及鼠标的信号。


NodePath focus_neighbor_bottom = NodePath("")

告诉 Godot 当用户按下键盘上的下方向键或游戏手柄上的下方向键时,默认应该将焦点移交给哪个节点。你可以通过编辑输入动作 ProjectSettings.input/ui_down 来修改具体的按键。该节点必须为 Control。如果未设置这个属性,Godot 会将焦点移交给该节点下方距离最近的 Control


NodePath focus_neighbor_left = NodePath("")

告诉 Godot 当用户按下键盘上的左方向键或游戏手柄上的左方向键时,默认应该将焦点移交给哪个节点。你可以通过编辑输入动作 ProjectSettings.input/ui_left 来修改具体的按键。该节点必须为 Control。如果未设置这个属性,Godot 会将焦点移交给该节点左侧距离最近的 Control


NodePath focus_neighbor_right = NodePath("")

告诉 Godot 当用户按下键盘上的右方向键或游戏手柄上的右方向键时,默认应该将焦点移交给哪个节点。你可以通过编辑输入动作 ProjectSettings.input/ui_right 来修改具体的按键。该节点必须为 Control。如果未设置这个属性,Godot 会将焦点移交给该节点右侧距离最近的 Control


NodePath focus_neighbor_top = NodePath("")

告诉 Godot 当用户按下键盘上的下方向键或游戏手柄上的下方向键时,默认应该将焦点移交给哪个节点。你可以通过编辑输入动作 ProjectSettings.input/ui_up 来修改具体的按键。该节点必须为 Control。如果未设置这个属性,Godot 会将焦点移交给该节点上方距离最近的 Control


NodePath focus_next = NodePath("")

告诉 Godot 在默认情况下,当用户按下键盘上的 Tab 时,应将焦点交给哪个节点。你可以通过编辑 ProjectSettings.input/ui_focus_next 的输入动作来更改按键。

如果未设置此属性,则 Godot 会将根据场景树中的附近节点选择一个“最佳猜测”。


NodePath focus_previous = NodePath("")

告诉 Godot 在默认情况下,当用户按下键盘上的 Shift + Tab 时,应将焦点交给哪个节点。你可以通过编辑 ProjectSettings.input/ui_focus_prev 的输入动作来更改按键。

如果未设置此属性,则 Godot 会将根据场景树中的附近节点选择一个“最佳猜测”。


Vector2 global_position

该节点的全局位置,相对于世界(通常为 CanvasLayer)。


GrowDirection grow_horizontal = 1

控制水平轴的方向,如果控件的水平最小尺寸更改为大于其当前尺寸,则控件应沿水平轴增长,因为控件始终必须至少为最小尺寸。


GrowDirection grow_vertical = 1

控制控件在垂直轴上的方向,如果控件的垂直最小尺寸更改为大于当前尺寸,则控件应沿该方向增大,因为控件始终必须至少为最小尺寸。


LayoutDirection layout_direction = 0

控制布局方向和文本书写方向。某些语言需要从右至左的布局(例如阿拉伯语和希伯来语)。


bool localize_numeral_system = true

  • void set_localize_numeral_system ( bool value )

  • bool is_localizing_numeral_system ( )

如果为 true,则会自动将代码行号、列表索引号、SpinBoxProgressBar 的值,从阿拉伯数字(0..9)转换为当前区域设置所使用的记数系统。

注意:不会自动转换文本中的数字,可以使用 TextServer.format_number 手动转换。


CursorShape mouse_default_cursor_shape = 0

此控件的默认光标形状。对于 Godot 插件和使用系统鼠标光标的应用程序或游戏很有用。

注意:在 Linux 上,形状可能会有所不同,具体取决于系统的光标主题。


MouseFilter mouse_filter = 0

控制控件是否能够通过 _gui_input 接收鼠标按钮输入事件,以及如何处理这些事件。还控制控件是否能接收 mouse_enteredmouse_exited 信号。参阅常量来了解每个常量的作用。


bool mouse_force_pass_scroll_events = true

  • void set_force_pass_scroll_events ( bool value )

  • bool is_force_pass_scroll_events ( )

启用后,即使 mouse_filter 被设置为 MOUSE_FILTER_STOP,由 _gui_input 处理的滚轮事件也会被传递给父控件。由于它默认为“真”,这允许嵌套的可滚动容器可以开箱即用。

如果不希望滚动事件进入 Node._unhandled_input 处理,则应该在用户界面的根部禁用它。


float offset_bottom = 0.0

该节点底部边缘与其父控件之间的距离,基于 anchor_bottom

偏移量通常由一个或多个父 Container 节点控制,因此如果你的节点是 Container 的直接子节点,则不应进行手动修改。移动节点或调整节点大小时,偏移量会自动更新。


float offset_left = 0.0

该节点左侧边缘与其父控件之间的距离,基于 anchor_left

偏移量通常由一个或多个父 Container 节点控制,因此如果你的节点是 Container 的直接子节点,则不应进行手动修改。移动节点或调整节点大小时,偏移量会自动更新。


float offset_right = 0.0

该节点右侧边缘与其父控件之间的距离,基于 anchor_right

偏移量通常由一个或多个父 Container 节点控制,因此如果你的节点是 Container 的直接子节点,则不应进行手动修改。移动节点或调整节点大小时,偏移量会自动更新。


float offset_top = 0.0

该节点顶部边缘与其父控件之间的距离,基于 anchor_top

偏移量通常由一个或多个父 Container 节点控制,因此如果你的节点是 Container 的直接子节点,则不应进行手动修改。移动节点或调整节点大小时,偏移量会自动更新。


Vector2 pivot_offset = Vector2(0, 0)

  • void set_pivot_offset ( Vector2 value )

  • Vector2 get_pivot_offset ( )

默认情况下,该节点的轴心位于左上角。更改 rotationscale 时,将围绕该轴心进行旋转或缩放。如果将该属性设置为 size / 2,则围绕的是该控件的中心点。


Vector2 position = Vector2(0, 0)

该节点的位置,相对于父节点。对应的是矩形的左上角。该属性不受 pivot_offset 的影响。


float rotation = 0.0

  • void set_rotation ( float value )

  • float get_rotation ( )

该节点围绕其轴心的旋转,单位为弧度。要更改轴心的位置,请参阅 pivot_offset

注意:该属性在检查器中以度为单位进行编辑。如果要在脚本中使用度数,请使用 rotation_degrees


float rotation_degrees

  • void set_rotation_degrees ( float value )

  • float get_rotation_degrees ( )

辅助属性,用于按度数访问 rotation 而不是弧度数。


Vector2 scale = Vector2(1, 1)

节点的缩放,相对于它的 size。更改该属性以围绕其 pivot_offset 缩放节点。该 Control 的 tooltip_text 也将根据该值进行缩放。

注意:该属性主要用于动画用途。要在项目中支持多种分辨率,请使用 文档 中所述的合适的视口拉伸模式,而不是单独缩放控件。

注意:FontFile.oversampling 考虑 Control scale。这意味着放大/缩小会导致位图字体和光栅化(非 MSDF)动态字体显得模糊或像素化。为确保无论缩放比例如何,文本都保持清晰,你可以通过启用 ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field(仅适用于默认项目字体);或在自定义字体的 DynamicFont 的导入选项中,启用多通道有符号距离场来启用 MSDF 字体渲染。对于系统字体,可以在检查器中启用 SystemFont.multichannel_signed_distance_field

注意:如果该 Control 节点是 Container 节点的子节点,则场景实例化时,缩放将重置为 Vector2(1, 1)。要在实例化时设置控件的缩放,请使用 await get_tree().process_frame 等待一帧,然后再设置其 scale 属性。


Node shortcut_context

  • void set_shortcut_context ( Node value )

  • Node get_shortcut_context ( )

Node 必须是被聚焦 Control 的父节点,才能激活快捷方式。如果为 null,则可以在任何控件获得焦点时激活该快捷方式(全局快捷方式)。这允许快捷方式只在用户聚焦 GUI 的特定区域时才被接受。


Vector2 size = Vector2(0, 0)

该节点的边界矩形的大小,使用该节点的坐标系。Container 节点会自动更新此属性。


BitField<SizeFlags> size_flags_horizontal = 1

  • void set_h_size_flags ( BitField<SizeFlags> value )

  • BitField<SizeFlags> get_h_size_flags ( )

告诉父 Container 节点应如何调整尺寸并将其放置在 X 轴上。请使用 SizeFlags 常量的组合来更改标志。查看常量以了解每个常量的作用。


float size_flags_stretch_ratio = 1.0

  • void set_stretch_ratio ( float value )

  • float get_stretch_ratio ( )

如果该节点及其至少一个邻居节点使用 SIZE_EXPAND 大小标志,则父 Container 将根据该属性让它占用更多或更少的空间。如果该节点的拉伸比为 2,其邻居节点的拉伸比为 1,则该节点将占用三分之二的可用空间。


BitField<SizeFlags> size_flags_vertical = 1

  • void set_v_size_flags ( BitField<SizeFlags> value )

  • BitField<SizeFlags> get_v_size_flags ( )

告诉父 Container 节点应如何调整尺寸并将其放置在 Y 轴上。请使用 SizeFlags 常量的组合来更改标志。查看常量以了解每个常量的作用。


Theme theme

  • void set_theme ( Theme value )

  • Theme get_theme ( )

该节点及其子 ControlWindow 所使用的 Theme 资源。如果子节点也设置了 Theme 资源,则会合并主题项,子节点的定义优先级更高。

注意:除非 Window 为嵌入式,否则窗口样式无效。


StringName theme_type_variation = &""

Control 用于查找其自有的主题项的主题类型变体的名称。当为空时,将使用节点的类名(例如 Button 用于 Button 控件),以及所有父类的类名(按继承顺序)。

设置后,该属性将最高优先级赋予指定名称的类型。这种类型又可以扩展另一种类型,形成依赖链。参见 Theme.set_type_variation。如果使用该类型或其基类型无法找到主题项,则查找会回退到依赖类名查找。

注意:要查找 Control 自有的项目,请使用各种 get_theme_* 方法且无需指定 theme_type

注意:主题项按树状顺序查找,从分支到根,其中每个 Control 节点的 theme 属性都将被检查。最早匹配任意类型名称/类名称的项将被返回。最后检查项目级的主题和默认主题。


String tooltip_text = ""

  • void set_tooltip_text ( String value )

  • String get_tooltip_text ( )

默认工具提示文本。如果 mouse_filter 属性不是 MOUSE_FILTER_IGNORE,则当用户的鼠标光标在此控件上停留片刻时,将出现工具提示。可以使用 ProjectSettings.gui/timers/tooltip_delay_sec 选项更改工具提示出现所需的时间。另见 get_tooltip

工具提示弹出窗口将使用默认实现,或者使用通过覆盖 _make_custom_tooltip 提供的自定义实现。默认工具提示包括一个 PopupPanelLabel,其主题属性可以使用 Theme 方法分别对 "TooltipPanel""TooltipLabel" 进行自定义。例如:

var style_box = StyleBoxFlat.new()
style_box.set_bg_color(Color(1, 1, 0))
style_box.set_border_width_all(2)
# 我们在这里假设`Theme`属性已经被事先分配了一个自定义的主题。
theme.set_stylebox("panel", "TooltipPanel", style_box)
theme.set_color("font_color", "TooltipLabel", Color(0, 1, 1))

方法说明

bool _can_drop_data ( Vector2 at_position, Variant data ) virtual const

Godot 调用这个方法来检查是否能够将来自某个控件 _get_drag_data 方法的 data 拖放到 at_positionat_position 使用的是这个控件的局部坐标系。

这个方法应该只用于检查数据。请在 _drop_data 中处理数据。

func _can_drop_data(position, data):
    # 如果和位置相关就检查 position
    # 否则只检查 data 即可
    return typeof(data) == TYPE_DICTIONARY and data.has("expected")

void _drop_data ( Vector2 at_position, Variant data ) virtual

Godot 调用这个方法把 data 传给你,这是从某个控件的 _get_drag_data 获得的结果。Godot 首先会调用 _can_drop_data 来检查是否允许把 data 拖放到 at_position,这里的 at_position 使用的是这个控件的局部坐标系。

func _can_drop_data(position, data):
    return typeof(data) == TYPE_DICTIONARY and data.has("color")

func _drop_data(position, data):
    var color = data["color"]

Variant _get_drag_data ( Vector2 at_position ) virtual

Godot 调用该方法来获取可以拖放到期望放置数据的控件上的数据。如果没有要拖动的数据,则返回 null。想要接收拖放数据的控件应该实现 _can_drop_data_drop_dataat_position 是该控件的局部位置。可以使用 force_drag 强制拖动。

可以使用 set_drag_preview 设置跟随鼠标显示数据的预览。设置预览的好时机就是在这个方法中。

func _get_drag_data(position):
    var mydata = make_data() # This is your custom method generating the drag data.
    set_drag_preview(make_preview(mydata)) # 这是你生成拖动数据预览的自定义方法。
    return mydata

Vector2 _get_minimum_size ( ) virtual const

由用户实现的虚方法。返回此控件的最小大小。替代 custom_minimum_size,以用于通过代码控制最小尺寸。实际的最小尺寸将是这两者的最大值(分别在每个轴上)。

如果未覆盖,则默认为 Vector2.ZERO

注意:当脚本被附加到已经覆盖其最小大小的 Control 节点(例如 LabelButtonPanelContainer 等)时,该方法将不会被调用。它只能用于最基本的 GUI 节点,如 ControlContainerPanel 等。


String _get_tooltip ( Vector2 at_position ) virtual const

用户实现的虚方法。返回位于控件局部坐标系中 at_position 位置的工具提示文本,工具提示一般会在鼠标停留在该控件上时显示。见 get_tooltip

注意:如果返回的是空 String,则不会显示工具提示。


void _gui_input ( InputEvent event ) virtual

由用户实现的虚方法。使用此方法处理和接受 UI 元素上的输入。请参阅 accept_event

点击控件的用法示例:

func _gui_input(event):
    if event is InputEventMouseButton:
        if event.button_index == MOUSE_BUTTON_LEFT and event.pressed:
            print("我已被点击 D:")

如果出现以下情况,则不会触发该事件:

* 在控件外点击(参阅_has_point);

* 控件将 mouse_filter 设置为 MOUSE_FILTER_IGNORE

* 控件被其上的另一个 Control 阻挡,该控件没有将 mouse_filter 设置为 MOUSE_FILTER_IGNORE

* 控件的父级已将 mouse_filter 设置为 MOUSE_FILTER_STOP 或已接受该事件;

* 它发生在父级的矩形之外,并且父级已启用 clip_contents

注意:事件位置相对于该控件原点。


bool _has_point ( Vector2 point ) virtual const

由用户实现的虚方法。返回给定的 point 是否在该控件内。

如果没有被覆盖,则默认行为是检查该点是否在控件的 Rect 内。

注意:如果要检查一个点是否在该控件内部,可以使用 Rect2(Vector2.ZERO, size).has_point(point)


Object _make_custom_tooltip ( String for_text ) virtual const

由用户实现的虚方法。返回一个 Control 节点,该节点取代默认节点以用作工具提示。for_text 包含 tooltip_text 属性的内容。

返回的节点必须是 Control 类型或 Control 派生类型。它可以有任何类型的子节点。当工具提示消失时它会被释放,因此请确保你始终提供一个新实例(如果你想使用场景树中预先存在的节点,你可以复制它并传递复制的实例)。当返回 null 或非控制节点时,将使用默认的工具提示。

返回的节点将作为子节点添加到 PopupPanel,因此你应该只提供该面板的内容。该 PopupPanel 可以使用 Theme.set_stylebox 为类型 "TooltipPanel" 设置主题(参见 tooltip_text 示例)。

注意:工具提示会被缩小到最小大小。如果你想确保它完全可见,你可能需要将其 custom_minimum_size 设置为非零值。

注意:返回时节点(和任何相关的子节点)应该是 CanvasItem.visible,否则,实例化它的视口将无法可靠地计算它的最小大小。

自定义构造节点的用法示例:

func _make_custom_tooltip(for_text):
    var label = Label.new()
    label.text = for_text
    return label

自定义场景实例的使用示例:

func _make_custom_tooltip(for_text):
    var tooltip = preload("res://some_tooltip_scene.tscn").instantiate()
    tooltip.get_node("Label").text = for_text
    return tooltip

Vector3i[] _structured_text_parser ( Array args, String text ) virtual const

用户定义的 BiDi 算法覆盖函数。

返回 Vector3i 文本范围和文本基础方向的 Array,顺序为从左至右。这些范围应该覆盖完整的来源文本 text,不应该存在重叠。BiDi 算法会对每个范围单独应用。


void accept_event ( )

将输入事件标记为已处理。一旦接受输入事件,传播就会停止,不会再传播到正在侦听 Node._unhandled_inputNode._unhandled_key_input 的节点。

注意:不会影响 Input 中的方法,只会影响事件的传播。


void add_theme_color_override ( StringName name, Color color )

为名称为 name 的主题 Color 创建本地覆盖项。为控件获取主题项目时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_color_override 移除。

另见 get_theme_color

覆盖标签颜色并在之后重置的示例:

# 存在名叫“MyLabel”的子 Label 节点,使用自定义的值覆盖其字体颜色。
$MyLabel.add_theme_color_override("font_color", Color(1, 0.5, 0))
# 重置该子标签的字体颜色。
$MyLabel.remove_theme_color_override("font_color")
# 也可以使用 Label 类型的默认值覆盖。
$MyLabel.add_theme_color_override("font_color", get_theme_color("font_color", "Label"))

void add_theme_constant_override ( StringName name, int constant )

为名称为 name 的主题常量创建本地覆盖项。为控件获取主题项目时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_constant_override 移除。

另见 get_theme_constant


void add_theme_font_override ( StringName name, Font font )

为名称为 name 的主题 Font 创建本地覆盖项。为控件获取主题项目时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_font_override 移除。

另见 get_theme_font


void add_theme_font_size_override ( StringName name, int font_size )

为名称为 name 的主题字体大小创建本地覆盖项。为控件获取主题项目时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_font_size_override 移除。

另见 get_theme_font_size


void add_theme_icon_override ( StringName name, Texture2D texture )

为名称为 name 的主题图标创建本地覆盖项。为控件获取主题项目时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_icon_override 移除。

另见 get_theme_icon


void add_theme_stylebox_override ( StringName name, StyleBox stylebox )

为名称为 name 的主题 StyleBox 创建本地覆盖项。为控件获取主题项目时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_stylebox_override 移除。

另见 get_theme_stylebox

通过创建副本来修改 StyleBox 属性的示例:

# 以下代码片段要求子节点 MyButton 分配了 StyleBoxFlat。
# 资源是跨实例共享的,因此我们需要制作其副本
# 来避免修改其他所有按钮的外观。
var new_stylebox_normal = $MyButton.get_theme_stylebox("normal").duplicate()
new_stylebox_normal.border_width_top = 3
new_stylebox_normal.border_color = Color(0, 1, 0.5)
$MyButton.add_theme_stylebox_override("normal", new_stylebox_normal)
# 移除样式盒覆盖项。
$MyButton.remove_theme_stylebox_override("normal")

void begin_bulk_theme_override ( )

防止 *_theme_*_override 方法发出 NOTIFICATION_THEME_CHANGED,直到 end_bulk_theme_override 被调用。


void end_bulk_theme_override ( )

结束批量主题覆盖更新。见 begin_bulk_theme_override


Control find_next_valid_focus ( ) const

找到下一个可以接受焦点的 Control,在树的下方。


Control find_prev_valid_focus ( ) const

找到上一个可以接受焦点的 Control,在树的上方。


Control find_valid_focus_neighbor ( Side side ) const

查找指定 Side 上可以接收焦点的下一个 Control

注意:这与 get_focus_neighbor 不同,后者返回指定焦点邻居的路径。


void force_drag ( Variant data, Control preview )

通过传递 datapreview 强制拖动并绕过 _get_drag_dataset_drag_preview。即使鼠标既没有在该控件悬停也没有在该控件上按下,拖动都将开始。

方法 _can_drop_data_drop_data 必须在想要接收拖放数据的控件上实现。


float get_anchor ( Side side ) const

返回指定 Side 的锚点。用于 anchor_bottomanchor_leftanchor_right、和 anchor_top 的取值方法。


Vector2 get_begin ( ) const

返回 offset_leftoffset_top。另请参阅 position


Vector2 get_combined_minimum_size ( ) const

返回 custom_minimum_sizeget_minimum_size 的组合最小大小。


CursorShape get_cursor_shape ( Vector2 position=Vector2(0, 0) ) const

返回控件在鼠标悬停时显示的鼠标指针形状。见 CursorShape


Vector2 get_end ( ) const

返回 offset_rightoffset_bottom


NodePath get_focus_neighbor ( Side side ) const

返回指定 Side 的焦点邻居。用于 focus_neighbor_bottomfocus_neighbor_leftfocus_neighbor_right、和 focus_neighbor_top 的取值方法。

注意:要查找特定 Side 上的下一个 Control,即使未指定邻居,也请使用 find_valid_focus_neighbor


Rect2 get_global_rect ( ) const

返回控件相对于所属画布的位置和大小。参见 global_positionsize

注意:如果节点本身或节点与画布之间的任何父级 CanvasItem 具有非默认旋转或倾斜,则生成的大小可能没有意义。

注意:Viewport.gui_snap_controls_to_pixels 设置为 true 会导致显示的控件和返回的 Rect2 之间的舍入不准确。


Vector2 get_minimum_size ( ) const

返回该控件的最小尺寸。见 custom_minimum_size


float get_offset ( Side offset ) const

返回指定 Side 的偏移。这是 offset_bottomoffset_leftoffset_rightoffset_top 的 getter 方法。


Vector2 get_parent_area_size ( ) const

返回父控件中占用的宽度/高度。


Control get_parent_control ( ) const

返回父控制节点。


Rect2 get_rect ( ) const

返回控件在包含节点的坐标系中的位置和大小。参见 positionscalesize

注意:如果 rotation 不是默认的旋转,那么得到的大小是没有意义的。

注意:Viewport.gui_snap_controls_to_pixels 设置为 true,会导致显示的控件和返回的 Rect2 之间的舍入不准确。


Vector2 get_screen_position ( ) const

返回该 Control 在全局屏幕坐标系中的位置(即考虑窗口的位置)。主要用于编辑器插件。

如果窗口是嵌入式的,则等于 global_position(见 Viewport.gui_embed_subwindows)。

显示弹出框的用法示例:

popup_menu.position = get_screen_position() + get_local_mouse_position()
popup_menu.reset_size()
popup_menu.popup()

Color get_theme_color ( StringName name, StringName theme_type="" ) const

从树中第一个匹配的 Theme 返回 Color,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的颜色项。如果省略 theme_type 则会使用当前控件的类名,如果定义了 theme_type_variation 则会优先使用。如果该类型为类名,则还会按照继承顺序检查父类。如果该类型为变种,则还会按照依赖顺序检查基础类型,然后再检查该控件的类名及其父类。

会首先考虑当前控件的本地覆盖项(见 add_theme_color_override),然后才是其 theme。各个父控件及其 theme 在当前控件之后考虑;会跳过没有 theme 的控件。如果树中没有匹配的 Theme,则会使用自定义项目 Theme(见 ProjectSettings.gui/theme/custom)和默认 Theme(见 ThemeDB)。

func _ready():
    # 获取当前 Control 类中定义的字体颜色,前提是存在。
    modulate = get_theme_color("font_color")
    # 获取 Button 类中定义的字体颜色。
    modulate = get_theme_color("font_color", "Button")

int get_theme_constant ( StringName name, StringName theme_type="" ) const

从树中第一个匹配的 Theme 返回常量,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的常量项。

详情请参阅 get_theme_color


float get_theme_default_base_scale ( ) const

从树中第一个匹配的 Theme 返回默认基础缩放值,该 Theme 中应存在有效的 Theme.default_base_scale 值。

详情请参阅 get_theme_color


Font get_theme_default_font ( ) const

从树中第一个匹配的 Theme 返回默认字体,该 Theme 中应存在有效的 Theme.default_font 值。

详情请参阅 get_theme_color


int get_theme_default_font_size ( ) const

从树中第一个匹配的 Theme 返回默认字体大小,该 Theme 中应存在有效的 Theme.default_font_size 值。

详情请参阅 get_theme_color


Font get_theme_font ( StringName name, StringName theme_type="" ) const

从树中第一个匹配的 Theme 返回 Font,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的字体项。

详情请参阅 get_theme_color


int get_theme_font_size ( StringName name, StringName theme_type="" ) const

从树中第一个匹配的 Theme 返回字体大小,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的字体大小项。

详情请参阅 get_theme_color


Texture2D get_theme_icon ( StringName name, StringName theme_type="" ) const

从树中第一个匹配的 Theme 返回图标,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的图标项。

详情请参阅 get_theme_color


StyleBox get_theme_stylebox ( StringName name, StringName theme_type="" ) const

从树中第一个匹配的 Theme 返回 StyleBox,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的样式盒项。

详情请参阅 get_theme_color


String get_tooltip ( Vector2 at_position=Vector2(0, 0) ) const

返回位于该控件局部坐标系中 at_position 位置的工具提示文本,工具提示一般会在鼠标停留在该控件上时显示。默认情况下返回的是 tooltip_text

覆盖这个方法可以自定义行为。见 _get_tooltip

注意:如果返回的是空 String,则不会显示工具提示。


void grab_click_focus ( )

创建一个尝试点击控件的 InputEventMouseButton。如果收到该事件,则该控件将获得焦点。

func _process(delta):
    grab_click_focus() # 点击另一个控制节点时,将改为点击该节点。

void grab_focus ( )

从别的控件上窃取焦点,从而成为聚焦的控件(见 focus_mode)。

注意:这个方法与 Object.call_deferred 配合使用会更加可靠,尤其是在 Node._ready 中调用时。


bool has_focus ( ) const

如果这是当前的焦点控件,则返回 true。见 focus_mode


bool has_theme_color ( StringName name, StringName theme_type="" ) const

如果树中存在匹配的 Theme 则返回 true,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的颜色项。

详情请参阅 get_theme_color


bool has_theme_color_override ( StringName name ) const

如果该 Control 节点中存在名为指定 name 的主题 Color 本地覆盖项,则返回 true

详情请参阅 add_theme_color_override


bool has_theme_constant ( StringName name, StringName theme_type="" ) const

如果树中存在匹配的 Theme 则返回 true,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的常量项。

详情请参阅 get_theme_color


bool has_theme_constant_override ( StringName name ) const

如果该 Control 节点中存在名为指定 name 的主题常量本地覆盖项,则返回 true

详情请参阅 add_theme_constant_override


bool has_theme_font ( StringName name, StringName theme_type="" ) const

如果树中存在匹配的 Theme 则返回 true,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的字体项。

详情请参阅 get_theme_color


bool has_theme_font_override ( StringName name ) const

如果该 Control 节点中存在名为指定 name 的主题 Font 本地覆盖项,则返回 true

详情请参阅 add_theme_font_override


bool has_theme_font_size ( StringName name, StringName theme_type="" ) const

如果树中存在匹配的 Theme 则返回 true,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的字体大小项。

详情请参阅 get_theme_color


bool has_theme_font_size_override ( StringName name ) const

如果该 Control 节点中存在名为指定 name 的主题字体大小本地覆盖项,则返回 true

详情请参阅 add_theme_font_size_override


bool has_theme_icon ( StringName name, StringName theme_type="" ) const

如果树中存在匹配的 Theme 则返回 true,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的图标项。

详情请参阅 get_theme_color


bool has_theme_icon_override ( StringName name ) const

如果该 Control 节点中存在名为指定 name 的主题图标本地覆盖项,则返回 true

详情请参阅 add_theme_icon_override


bool has_theme_stylebox ( StringName name, StringName theme_type="" ) const

如果树中存在匹配的 Theme 则返回 true,该 Theme 中应存在指定名称 name 和主题类型 theme_type 的样式盒项。

详情请参阅 get_theme_color


bool has_theme_stylebox_override ( StringName name ) const

如果该 Control 节点中存在名为指定 name 的主题 StyleBox 本地覆盖项,则返回 true

详情请参阅 add_theme_stylebox_override


bool is_drag_successful ( ) const

如果拖放操作成功则返回 true,是 Viewport.gui_is_drag_successful 的替代方案。

建议与 Node.NOTIFICATION_DRAG_END 配合使用。


bool is_layout_rtl ( ) const

如果布局是从右至左的,则返回 true


void release_focus ( )

放弃焦点。不会让其他控件能够接收键盘输入。


void remove_theme_color_override ( StringName name )

移除名为指定 name 的主题 Color 本地覆盖项,该覆盖项由 add_theme_color_override 或检查器面板添加的。


void remove_theme_constant_override ( StringName name )

移除名为指定 name 的主题常量本地覆盖项,该覆盖项由 add_theme_constant_override 或检查器面板添加的。


void remove_theme_font_override ( StringName name )

移除名为指定 name 的主题 Font 本地覆盖项,该覆盖项由 add_theme_font_override 或检查器面板添加的。


void remove_theme_font_size_override ( StringName name )

移除名为指定 name 的主题字体大小本地覆盖项,该覆盖项由 add_theme_font_size_override 或检查器面板添加的。


void remove_theme_icon_override ( StringName name )

移除名为指定 name 的主题图标本地覆盖项,该覆盖项由 add_theme_icon_override 或检查器面板添加的。


void remove_theme_stylebox_override ( StringName name )

移除名为指定 name 的主题 StyleBox 本地覆盖项,该覆盖项由 add_theme_stylebox_override 或检查器面板添加的。


void reset_size ( )

将大小重置为 get_combined_minimum_size。等价于调用 set_size(Vector2())(或任何小于最小值的大小)。


void set_anchor ( Side side, float anchor, bool keep_offset=false, bool push_opposite_anchor=true )

将指定 Side 的锚点设置为 anchor。用于 anchor_bottomanchor_leftanchor_right、和 anchor_top 的设值函数。

如果 keep_offsettrue,则偏移量不会在该操作后更新。

如果 push_opposite_anchortrue,并且相对的锚点与该锚点重叠,则相对的锚点的值将被覆盖。例如,当将左锚点设置为 1 且右锚点的值为 0.5 时,右锚点的值也将为 1。如果 push_opposite_anchorfalse,则左锚点的值将为 0.5。


void set_anchor_and_offset ( Side side, float anchor, float offset, bool push_opposite_anchor=false )

工作原理与 set_anchor 相同,但取代 keep_offset 参数和自动更新的偏移,它允许你自己设置偏移量(参见 set_offset)。


void set_anchors_and_offsets_preset ( LayoutPreset preset, LayoutPresetMode resize_mode=0, int margin=0 )

设置锚点预设和偏移预设。参见 set_anchors_presetset_offsets_preset


void set_anchors_preset ( LayoutPreset preset, bool keep_offsets=false )

将锚点设置为 LayoutPreset 枚举中的 preset。这是相当于在 2D 编辑器中使用布局菜单的代码。

如果 keep_offsetstrue,则控件的位置也将被更新。


void set_begin ( Vector2 position )

同时设置 offset_leftoffset_top。相当于改变 position


void set_drag_forwarding ( Callable drag_func, Callable can_drop_func, Callable drop_func )

转发该控件的 _get_drag_data_can_drop_data_drop_data 虚函数的处理,以委托给可调用体。

对于每个参数,如果不为空,则使用委托的可调用体,否则使用本地(虚)函数。

每个可调用体的函数格式应该与上面描述的虚函数完全相同。


void set_drag_preview ( Control control )

在鼠标指针处显示给定的控件。调用此方法的好时机是在 _get_drag_data 中。控件不得位于场景树中。你不应释放控件,也不应在拖动持续时间之外保留对控件的引用。拖拽结束后它会自动删除。

@export var color = Color(1, 0, 0, 1)

func _get_drag_data(position):
    #使用不在树中的控件
    var cpb = ColorPickerButton.new()
    cpb.color = color
    cpb.size = Vector2(50, 50)
    set_drag_preview(cpb)
    return color

void set_end ( Vector2 position )

同时设置 offset_rightoffset_bottom


void set_focus_neighbor ( Side side, NodePath neighbor )

将指定 Side 的焦点邻居设置为节点路径 neighbor 处的 Control。这是 focus_neighbor_bottomfocus_neighbor_leftfocus_neighbor_rightfocus_neighbor_top 的 setter 方法。


void set_global_position ( Vector2 position, bool keep_offsets=false )

global_position 设置为给定的 position

如果 keep_offsetstrue,则将更新控件的锚点而不是偏移量。


void set_offset ( Side side, float offset )

将指定 Side 的偏移设置为 offset。用于 offset_bottomoffset_leftoffset_right、和 offset_top 的设值方法。


void set_offsets_preset ( LayoutPreset preset, LayoutPresetMode resize_mode=0, int margin=0 )

将偏移设置为 LayoutPreset 枚举中的 preset。这是相当于在 2D 编辑器中使用布局菜单的代码。

将参数 resize_modeLayoutPresetMode 中的常量一起使用,以更好地确定 Control 的最终大小。如果与更改尺寸大小的预设一起使用,则将忽略常量尺寸大小,例如 PRESET_LEFT_WIDE

使用参数 margin 来确定 Control 和边缘之间的间隙。


void set_position ( Vector2 position, bool keep_offsets=false )

position 设置为给定的 position

如果 keep_offsetstrue,则将更新控件的锚点而不是偏移量。


void set_size ( Vector2 size, bool keep_offsets=false )

设置大小(参见 size)。

如果 keep_offsetstrue,则将更新控件的锚点而不是偏移量。


void update_minimum_size ( )

使该节点和直至顶级的父节点中的大小缓存无效。旨在当返回值更改时与 get_minimum_size 一起使用。直接设置 custom_minimum_size 将自动调用该方法。


void warp_mouse ( Vector2 position )

将鼠标光标移动到 position,相对于该 Controlposition

注意:warp_mouse 仅在 Windows、macOS 和 Linux 上受支持。它在 Android、iOS 和 Web 上没有效果。