Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
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，你需要混合使用从 Control 和 Container 节点继承的 UI 元素。
用户界面节点与输入
Godot 使用视口来传播输入事件。视口负责将 InputEvent 传播给它的子节点。因为 SceneTree.root 是 Window，所以游戏中的所有 UI 元素都会自动进行传播。
输入事件通过调用 Node._input 在 SceneTree 中传播，从根节点传播到所有子节点。对 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.get 和 Object.set 访问它们的值。请改用这个类的 get_theme_* 和 add_theme_*_override 方法。
教程¶
属性¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
BitField<SizeFlags> |
|
|
|
||
BitField<SizeFlags> |
|
|
|
||
|
方法¶
信号¶
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_horizontal 和 size_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_horizontal 和 size_flags_vertical 一起使用。
注意：设置这个标志相当于没有任何大小标志。
SizeFlags SIZE_FILL = 1
告诉父级 Container 扩展该节点的边界以填充所有可用空间，而无需推动任何其他节点。它与收缩大小标志互斥。与 size_flags_horizontal 和 size_flags_vertical 一起使用。
SizeFlags SIZE_EXPAND = 2
告诉父级 Container 让该节点占用你标记的轴上的所有可用空间。如果将多个相邻节点设置为扩展，它们将根据其拉伸比共享空间。见 size_flags_stretch_ratio。用于 size_flags_horizontal 和 size_flags_vertical。
SizeFlags SIZE_EXPAND_FILL = 3
将该节点的大小标志设置为填充和扩展。有关详细信息，请参阅 SIZE_FILL 和 SIZE_EXPAND。
SizeFlags SIZE_SHRINK_CENTER = 4
告诉父级 Container 将节点置于可用空间的中心。它与 SIZE_FILL 以及其他收缩大小标志互斥，但可以在某些容器中与 SIZE_EXPAND 一起使用。与 size_flags_horizontal 和 size_flags_vertical 一起使用。
SizeFlags SIZE_SHRINK_END = 8
告诉父级 Container 将节点与其末端对齐，即底部或右侧。它与 SIZE_FILL 以及其他收缩大小标志互斥，但可以在某些容器中与 SIZE_EXPAND 一起使用。与 size_flags_horizontal 和 size_flags_vertical 一起使用。
enum MouseFilter:
MouseFilter MOUSE_FILTER_STOP = 0
在控件上点击时，将通过 _gui_input 收到鼠标移动输入事件和鼠标按钮输入事件。控件能够接收到 mouse_entered 和 mouse_exited 信号。这些事件将自动被标记为已处理，不会进一步传播到其他控件。这也会导致其他控件中的信号被阻止。
MouseFilter MOUSE_FILTER_PASS = 1
在控件上点击时，将通过 _gui_input 收到鼠标移动输入事件和鼠标按钮输入事件。并且控件能够接收到 mouse_entered 和 mouse_exited 信号。如果此控件不处理事件，则将考虑其父控件（如果有的话），依此类推，直到没有更多的父控件可以处理该事件。这也允许信号在其他控件中触发。如果没有控件处理它，该事件将被传递到 Node._shortcut_input 进行进一步处理。
MouseFilter MOUSE_FILTER_IGNORE = 2
在控件上点击时，不会通过 _gui_input 收到鼠标移动输入事件和鼠标按钮输入事件，也不会接收到 mouse_entered 和 mouse_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</