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 信号。如果此控件不处理事件,则将考虑其父控件(如果有的话)