Control

Inherits: CanvasItem < Node < Object

Inherited By: BaseButton, ColorRect, Container, GraphEdit, ItemList, Label, LineEdit, NinePatchRect, Panel, Popup, Range, ReferenceRect, RichTextLabel, Separator, Tabs, TextEdit, TextureRect, Tree, VideoPlayer

所有用户界面节点都从 Control 继承。控件的锚点和边距相对于其父级调整其位置和大小。

描述

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

更多关于 Godot 的 UI 系统、锚点、边距和容器的信息，请参阅手册中的相关教程。 要构建灵活的 UI，您需要混合使用从 Control 和 Container 节点继承的 UI 元素。

用户界面节点和输入

Godot 首先通过调用 Node._input 将输入事件发送到场景的根节点。 Node._input 将事件沿节点树向下转发到鼠标光标下或键盘焦点上的节点。 为此，它调用 MainLoop._input_event。 调用 accept_event 以便没有其他节点收到该事件。 一旦你接受一个输入，它就会被处理，所以 Node._unhandled_input 不会处理它。

只有一个 Control 节点可以处于键盘焦点。 只有处于焦点的节点才会接收键盘事件。 要获得焦点，请调用 grab_focus。在另一个节点获得聚焦时 Control 节点会失去焦点，或者您隐藏焦点中的节点。

将 mouse_filter 设置为 MOUSE_FILTER_IGNORE 以告诉 Control 节点忽略鼠标或触摸事件。 如果您在按钮顶部放置一个图标，您将需要它。

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

注意： 主题项目不是 Object 的属性。这意味着你无法使用 Object.get 和 Object.set 访问它们的值。请换用 get_color、get_constant、get_font、get_icon、get_stylebox，以及这个类提供的 add_*_override 方法。

教程

• GUI tutorial index

• Custom drawing in 2D

• Control node gallery

• All GUI Demos

属性

方法

信号

• focus_entered ( )

在节点获得键盘焦点时发出。

• focus_exited ( )

当节点失去键盘焦点时发出。

• gui_input ( InputEvent event )

在节点收到InputEvent时发出。

• minimum_size_changed ( )

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

• modal_closed ( )

当模态控件Control被关闭时触发。参阅show_modal。

• mouse_entered ( )

当鼠标进入控件的Rect区域时触发，只要其mouse_filter允许事件到达。

注意： 如果鼠标在进入父控件的Rect区域之前进入子Control节点，在鼠标移动到父控件的Rect区域之前，不会发出mouse_entered。

• mouse_exited ( )

当鼠标离开控件的Rect区域时触发，只要其mouse_filter允许事件到达。

注意： 如果鼠标进入一个子Control节点，即使鼠标光标仍然在父Rect区域内，mouse_exited也将触发。

• resized ( )

当控件更改大小时发出。

• size_flags_changed ( )

当大小标志之一更改时发出。请参阅size_flags_horizontal和size_flags_vertical。

枚举

enum FocusMode:

• FOCUS_NONE = 0 —- 该节点无法获取焦点。在 focus_mode 中使用。

• FOCUS_CLICK = 1 —- 该节点只能通过鼠标点击获取焦点。在 focus_mode 中使用。

• FOCUS_ALL = 2 —- 该节点可以通过使用鼠标点击或使用键盘上的箭头和 Tab 键获取焦点。在 focus_mode 中使用。

enum CursorShape:

• CURSOR_ARROW = 0 —- 当用户将节点悬停时，显示系统的箭头鼠标光标。与mouse_default_cursor_shape成员一起使用。

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

• CURSOR_POINTING_HAND = 2 —- 当用户将节点悬停时，显示系统的手形鼠标光标。

• CURSOR_CROSS = 3 —- 当用户将鼠标悬停在节点上时，显示系统的交叉鼠标光标。

• CURSOR_WAIT = 4 —- 当用户悬停节点时，显示系统的等待鼠标光标，通常是一个沙漏。

• CURSOR_BUSY = 5 —- 当用户悬停节点时，显示系统繁忙的鼠标光标。通常是一个沙漏。

• CURSOR_DRAG = 6 —- 当用户悬停在节点上时，显示系统的拖动鼠标光标，通常是一个闭合的拳头或十字符号。它告诉用户他们当前正在拖动一个项目，就像场景码头中的节点一样。

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

• CURSOR_FORBIDDEN = 8 —- 当用户悬停节点时，显示系统禁止的鼠标光标。通常是一个交叉的圆圈。

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

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

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

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

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

• CURSOR_VSPLIT = 14 —- 当用户将节点悬停时，显示系统的垂直拆分鼠标光标。在 Windows 上，它与 CURSOR_VSIZE 相同。

• CURSOR_HSPLIT = 15 —- 当用户将节点悬停时，显示系统的水平拆分鼠标光标。在Windows上，它与CURSOR_HSIZE相同。

• CURSOR_HELP = 16 —- 当用户将节点悬停在一个节点上时，显示系统的帮助鼠标光标，一个问号。

enum LayoutPreset:

• PRESET_TOP_LEFT = 0 —- 将所有4个定位点对齐到父控件边界的左上角。与set_anchors_preset一起使用。

• PRESET_TOP_RIGHT = 1 —- 将所有4个定位点对齐到父控件边界的右上角。与set_anchors_preset一起使用。

• PRESET_BOTTOM_LEFT = 2 —- 将所有4个定位点对齐到父控件的边界的左下角。与set_anchors_preset一起使用。

• PRESET_BOTTOM_RIGHT = 3 —- 将所有4个定位点对齐到父控件的边界的右下角。与set_anchors_preset一起使用。

• PRESET_CENTER_LEFT = 4 —- 将所有4个定位点对齐到父控件边界的左边缘的中心。与set_anchors_preset一起使用。

• PRESET_CENTER_TOP = 5 —- 将所有4个定位点对齐到父控件边界的上边缘的中心。与set_anchors_preset一起使用。

• PRESET_CENTER_RIGHT = 6 —- 将所有4个锚点对齐到父控件边界右边缘的中心。与set_anchors_preset一起使用。

• PRESET_CENTER_BOTTOM = 7 —- 将所有 4 个锚捕捉到父控制边界底部边缘的中心。使用set_anchors_preset。

• PRESET_CENTER = 8 —- 将所有4个定位点对齐到父控件边界的中心。与set_anchors_preset一起使用。

• PRESET_LEFT_WIDE = 9 —- 将所有4个定位点对齐到父控件的左边缘。左边距相对于节点父节点的左边缘，而上边距相对于节点父节点的左上角。与set_anchors_preset一起使用。

• PRESET_TOP_WIDE = 10 —- 将所有4个定位点对齐到父控件的顶部边缘。左侧边距相对于节点父节点的左上角，顶部边距相对于顶部的边缘，右侧边距相对于节点的父节点。与set_anchors_preset一起使用。

• PRESET_RIGHT_WIDE = 11 —- 将所有4个定位点对齐到父控件的顶部边缘。左侧边距相对于节点父节点的左上角，顶部边距相对于顶部的边缘，右侧边距相对于节点的父节点。与set_anchors_preset一起使用。

• PRESET_BOTTOM_WIDE = 12 —- 将所有4个定位点对齐到父控件的底部边缘。左侧边距相对于节点父节点的左下角，底部边距相对于底部的边缘，而右侧边距相对于节点的右下角。与set_anchors_preset一起使用。

• PRESET_VCENTER_WIDE = 13 —- 将所有4个锚点对齐到一条垂直线，该垂直线将父控件切成两半。与set_anchors_preset一起使用。

• PRESET_HCENTER_WIDE = 14 —- 将所有4个锚点对齐到一条水平线，该水平线将父控件切成两半。与set_anchors_preset一起使用。

• PRESET_WIDE = 15 —- 将所有4个定位点对齐到父控件的各个角。应用此预设后，将所有4个页边距设置为0，Control将适合其上级控件。这等效于编辑器中的“全角”布局选项。与set_anchors_preset一起使用。

enum LayoutPresetMode:

• PRESET_MODE_MINSIZE = 0 —- 控件将被调整为最小尺寸。

• PRESET_MODE_KEEP_WIDTH = 1 —- 控件的宽度不会改变。

• PRESET_MODE_KEEP_HEIGHT = 2 —- 控件的高度不会改变。

• PRESET_MODE_KEEP_SIZE = 3 —- 控件的大小不会改变。

enum SizeFlags:

• SIZE_FILL = 1 —- 告诉父Container扩展此节点的边界，以在不推其他节点的情况下填充所有可用空间。使用size_flags_horizontal和size_flags_vertical。

• SIZE_EXPAND = 2 —- 告诉父级Container让该节点占用您标记的轴上的所有可用空间。如果将多个相邻节点设置为扩展，它们将根据其拉伸比共享空间。参阅size_flags_stretch_ratio。与size_flags_horizontal和size_flags_vertical一起使用。

• SIZE_EXPAND_FILL = 3 —- 将节点的大小标志设置为同时填充和扩展。有关更多信息，请参阅上面的2个常量。

• SIZE_SHRINK_CENTER = 4 —- 告诉父级 Container 使节点本身居中。它基于控件的包围框居中，因此它不适用于 fill 或 expand 尺寸标志。与 size_flags_horizontal 和 size_flags_vertical 一起使用。

• SIZE_SHRINK_END = 8 —- 告诉父级Container将节点与其末端（底部或右侧）对齐。它不适用于fill或expand size标志。与size_flags_horizontal和size_flags_vertical一起使用。

enum MouseFilter:

• MOUSE_FILTER_STOP = 0 —- 被点击时，控件将通过 _gui_input 收到鼠标按钮输入事件。控件能够接收到 mouse_entered 和 mouse_exited 信号。这些事件将自动被标记为已处理，不会进一步传播到其他控件，因此相关的信号也不会在其他控件中触发。

• MOUSE_FILTER_PASS = 1 —- 被点击时，控件将通过 _gui_input 收到鼠标按钮输入事件。控件能够接收 mouse_entered 和 mouse_exited 信号。如果此控件未处理事件，则将考虑其父控件（如果有的话），并依此类推，直到不再有可能处理它的父控件为止。因此，相关的信号可以在其他控件中触发。即使根本没有控件处理过该事件，该事件仍将被自动处理，因此不会触发未处理的输入。

• MOUSE_FILTER_IGNORE = 2 —- 该控件不会通过 _gui_input 收到鼠标按钮输入事件，也不会接收到 mouse_entered 和 mouse_exited 信号。这不会阻止其他控件接收这些事件或触发信号。被忽略的事件将不会被自动处理。

enum GrowDirection:

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

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

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

enum Anchor:

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

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

常量

• NOTIFICATION_RESIZED = 40 —- 当节点更改大小时发送。使用rect_size获取新大小。

• NOTIFICATION_MOUSE_ENTER = 41 —- 当鼠标指针进入节点时发送。

• NOTIFICATION_MOUSE_EXIT = 42 —- 当鼠标指针退出节点时发送。

• NOTIFICATION_FOCUS_ENTER = 43 —- 当节点获得焦点时发送。

• NOTIFICATION_FOCUS_EXIT = 44 —- 当节点失去焦点时发送。

• NOTIFICATION_THEME_CHANGED = 45 —- 当节点的 theme 改变时，就在Godot重绘控件之前发送。当你调用add_*_override方法之一时发生。

• NOTIFICATION_MODAL_CLOSE = 46 —- 当一个打开的模态对话框关闭时发送。参阅show_modal。

• NOTIFICATION_SCROLL_BEGIN = 47 —- 当此节点在已开始滚动的ScrollContainer内部时发送。

• NOTIFICATION_SCROLL_END = 48 —- 当此节点在已停止滚动的ScrollContainer内部时发送。

属性说明

• float anchor_bottom

将节点的底部边缘锚定到其父控件的原点，中心或末端。当节点移动或更改大小时，它会更改底部边距的更新方式。为了方便起见，可以使用Anchor常量之一。

• float anchor_left

将节点的左边缘锚定到其父控件的原点，中心或末端。当节点移动或更改大小时，它会更改左侧边距的更新方式。为了方便起见，可以使用Anchor常量之一。

• float anchor_right

将节点的右边缘锚定到其父控件的原点，中心或末端。当节点移动或更改大小时，它会更改右边距的更新方式。为了方便起见，可以使用Anchor常量之一。

• float anchor_top

锚定节点的顶部边缘到原点、中心或其父控件的末端。当节点移动或改变大小时，它可以改变顶边的更新方式。为了便捷，你可以使用Anchor常数之一。

• FocusMode focus_mode

控件的焦点访问模式（“无”，“单击”或“全部”）。只能同时集中一个控件，它将接收键盘信号。

• NodePath focus_neighbour_bottom

告诉Godot，默认情况下，如果用户按下键盘上的向下箭头或游戏手柄上的向下箭头，则应将焦点对准哪个节点。您可以通过编辑ui_down输入操作来更改键。该节点必须是Control。如果未设置此属性，则Godot会将焦点放在该控件底部最接近的Control。

• NodePath focus_neighbour_left

告诉Godot，默认情况下，如果用户按下键盘上的向左箭头或游戏手柄上的向左键，应该将焦点对准键盘上的哪个节点。您可以通过编辑ui_left输入操作来更改键。该节点必须是Control。如果未设置此属性，则Godot会将焦点放在该控件左侧最接近的Control。

• NodePath focus_neighbour_right

告诉Godot，如果用户按键盘上的右键或默认的游戏手柄上的右键，它应该把键盘焦点给哪个节点。你可以通过编辑ui_right输入动作来改变这个键。该节点必须是一个Control。如果没有设置这个属性，Godot将把焦点交给离这个节点底部最近的Control。

• NodePath focus_neighbour_top

告诉Godot默认情况下，如果用户按下键盘上的顶部箭头或游戏手柄上的顶部，则应该将焦点对准键盘上的哪个节点。您可以通过编辑ui_top输入操作来更改键。该节点必须是Control。如果未设置此属性，则Godot会将焦点放在该控件底部最接近的Control。

• NodePath focus_next

告诉Godot，如果用户默认按键盘上的Tab键，它应该把键盘焦点给哪个节点。你可以通过编辑ui_focus_next输入动作来改变这个键。

如果这个属性没有设置，Godot会根据场景树中的周围节点选择一个 “最佳猜测”。

• NodePath focus_previous

告诉Godot，如果用户按键盘上的Shift+Tab键，它应该把键盘焦点给哪个节点，这是默认。你可以通过编辑ui_focus_prev输入动作来改变这个键。

如果没有设置这个属性，Godot会根据场景树中的周围节点选择一个 “最佳猜测”。

• GrowDirection grow_horizontal

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

• GrowDirection grow_vertical

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

• String hint_tooltip

改变工具提示的文本。当用户的鼠标光标在这个控件上停留片刻，工具提示就会出现，前提是mouse_filter属性非MOUSE_FILTER_IGNORE。你可以用项目设置中的gui/timers/tooltip_delay_sec选项改变工具提示出现的时间。

工具提示的弹出将使用默认的实现，或者你可以通过覆盖_make_custom_tooltip提供一个自定义的实现。默认的工具提示包括一个PopupPanel和Label，其主题属性可以通过"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。
theme.set_stylebox("panel", "TooltipPanel", style_box)
theme.set_color("font_color", "TooltipLabel", Color(0, 1, 1))

• bool input_pass_on_modal_close_click

启用当你关闭控件模态时，输入是否传播。

如果false，在视窗输入事件处理时停止事件处理。视窗首先隐藏模态，之后将输入标记为已处理。

• float margin_bottom

节点底边与其父控件之间的距离，基于anchor_bottom。

边距通常由一个或多个父Container节点控制，因此，如果您的节点是Container的直接子级，则不应手动修改它们。当您移动或调整节点大小时，边距会自动更新。

• float margin_left

节点的左边缘与其父控件之间的距离，基于anchor_left。

边距通常由一个或多个父Container节点控制，因此，如果您的节点是Container的直接子级，则不应手动修改它们。当您移动或调整节点大小时，边距会自动更新。

• float margin_right

节点的右边缘与其父控件之间的距离，基于anchor_right。

边距通常由一个或多个父Container节点控制，因此，如果您的节点是Container的直接子级，则不应手动修改它们。当您移动或调整节点大小时，边距会自动更新。

• float margin_top

节点的顶边与其父控件之间的距离，基于anchor_top。

边距通常由一个或多个父 Container 节点控制，所以如果您的节点是 Container 的直接子节点，您不应该手动修改它们。当您移动或调整节点大小时，边距会自动更新。

• CursorShape mouse_default_cursor_shape

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

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

• MouseFilter mouse_filter

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

• bool rect_clip_content

启用是否应将基于CanvasItem的子控件渲染到该控件的矩形上。如果true，则不会渲染子控件中明显在矩形之外的部分。

• Vector2 rect_global_position

节点相对于世界的全局位置（通常是窗口的左上角）。

• Vector2 rect_min_size

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

• Vector2 rect_pivot_offset

默认情况下，节点的轴是其左上角。当您更改其rect_scale时，它将围绕此枢轴进行缩放。将此属性设置为rect_size / 2，以将枢轴在节点的矩形中居中。

• Vector2 rect_position

节点相对于其父节点的位置。它对应于矩形的左上角。该属性不受rect_pivot_offset的影响。

• float rect_rotation

节点围绕其枢轴的旋转（以度为单位）。请参阅rect_pivot_offset更改枢轴的位置。

• Vector2 rect_scale

The node’s scale, relative to its rect_size. Change this property to scale the node around its rect_pivot_offset. The Control’s hint_tooltip will also scale according to this value.

Note: This property is mainly intended to be used for animation purposes. Text inside the Control will look pixelated or blurry when the Control is scaled. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the documentation instead of scaling Controls individually.

Note: If the Control node is a child of a Container node, the scale will be reset to Vector2(1, 1) when the scene is instanced. To set the Control’s scale when it’s instanced, wait for one frame using yield(get_tree(), "idle_frame") then set its rect_scale property.

• Vector2 rect_size

节点边界矩形的大小，以像素为单位。 Container节点会自动更新此属性。

• int size_flags_horizontal

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

• float size_flags_stretch_ratio

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

• int size_flags_vertical

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

• Theme theme

更改此属性将替换该节点及其所有Control子级使用的当前Theme资源。

方法说明

• bool _clips_input ( ) virtual

用户要实现的虚方法。返回是否应为该控件矩形之外的子控件调用 _gui_input。输入将被剪切到此 Control 的 Rect 上。与 rect_clip_content 相似，但不影响可见性。

如果未覆盖，则默认为 false。

• Vector2 _get_minimum_size ( ) virtual

Virtual method to be implemented by the user. Returns the minimum size for this control. Alternative to rect_min_size for controlling minimum size via code. The actual minimum size will be the max value of these two (in each axis separately).

If not overridden, defaults to Vector2.ZERO.

Note: This method will not be called when the script is attached to a Control node that already overrides its minimum size (e.g. Label, Button, PanelContainer etc.). It can only be used with most basic GUI nodes, like Control, Container, Panel etc.

• void _gui_input ( InputEvent event ) virtual

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

例：单击控件。

func _gui_input(event):
    if event is InputEventMouseButton:
        if event.button_index == BUTTON_LEFT and event.pressed:
            print("I've been clicked D:")

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

* 在控件外点击（参阅has_point）；

* 控件将 mouse_filter 设置为 MOUSE_FILTER_IGNORE；

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

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

* 它发生在父级的矩形之外，并且父级已启用 rect_clip_content 或 _clips_input。

注： 事件坐林标相对于控件原点。

• Control _make_custom_tooltip ( String for_text ) virtual

由用户实现的虚方法。返回一个 Control 节点，该节点应用作工具提示而不是默认节点。 for_text 包含 hint_tooltip 属性的内容。

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

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

注意：工具提示缩小到最小尺寸。如果你想确保它完全可见，需将其 rect_min_size 设置为非零值。

自定义构建节点的使用示例：

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://SomeTooltipScene.tscn").instance()
    tooltip.get_node("Label").text = for_text
    return tooltip

• void accept_event ( )

将输入事件标记为已处理。一旦接受输入事件，它就会停止传播，甚至传播到正在侦听Node._unhandled_input或Node._unhandled_key_input的节点。

• void add_color_override ( String name, Color color )

使用指定的 name 为主题 Color 创建本地覆盖项。获取控件的主题项时，本地覆盖项始终优先。无法删除覆盖项，但可以使用相应的默认值覆盖它。

参阅get_color。

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

# 给定子标签节点"MyLabel"，用自定义值覆盖其字体颜色。
$MyLabel.add_color_override("font_color", Color(1, 0.5, 0))
# 重置子标签的字体颜色。
$MyLabel.add_color_override("font_color", get_color("font_color", "Label"))

• void add_constant_override ( String name, int constant )

为指定 name 的主题常量创建本地覆盖项。获取控件的主题项时，本地覆盖项始终优先。无法删除覆盖项，但可以使用相应的默认值覆盖它。

参阅get_constant。

• void add_font_override ( String name, Font font )

使用指定的 name 为主题 Font 创建本地覆盖项。获取控件的主题项时，本地覆盖项始终优先。可以通过为其分配 null 值来删除覆盖。

参阅get_font。

• void add_icon_override ( String name, Texture texture )

为指定 name 的主题图标创建本地覆盖项。获取控件的主题项时，本地覆盖项始终优先。可以通过为其分配 null 值来删除覆盖。

参阅get_icon。

• void add_shader_override ( String name, Shader shader )

为指定 name 的主题着色器创建本地覆盖项。获取控件的主题项时，本地覆盖项始终优先。可以通过为其分配 null 值来删除覆盖。

• void add_stylebox_override ( String name, StyleBox stylebox )

为主题 StyleBox 创建名为 name 的本地覆盖项。获取控件的主题项时，本地覆盖项始终优先。可以通过为其分配 null 值来删除覆盖。

参阅 get_stylebox。

通过复制来修改 StyleBox 中的属性的示例：

# 下面的代码片段假设子节点 MyButton 分配了一个 StyleBoxFlat。
# 资源是跨实例共享的，所以我们需要复制它
# 以避免修改所有其他按钮的外观。
var new_stylebox_normal = $MyButton.get_stylebox("normal").duplicate()
new_stylebox_normal.border_width_top = 3
new_stylebox_normal.border_color = Color(0, 1, 0.5)
$MyButton.add_stylebox_override("normal", new_stylebox_normal)
# 删除样式盒覆盖。
$MyButton.add_stylebox_override("normal", null)

• bool can_drop_data ( Vector2 position, Variant data ) virtual

Godot 调用此方法来测试是否可以将控件的 get_drag_data 的 data 放在 position 处。position 在相对于该控件的。

此方法仅应用于测试数据。处理 drop_data 中的数据。

func can_drop_data(position, data):
    # 需要时可以检查 position
    # 否则只检查 data 即可
    return typeof(data) == TYPE_DICTIONARY and data.has("expected")

• void drop_data ( Vector2 position, Variant data ) virtual

Godot调用此方法以将控件的get_drag_data结果中的data传递给您。 Godot首先调用can_drop_data来测试是否允许data在position处删除，其中position对于此控件而言是本地的。

func can_drop_data(position, data):
    return typeof(data) == TYPE_DICTIONARY and data.has("color")
func drop_data(position, data):
    color = data["color"]

• Control find_next_valid_focus ( ) const

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

• Control find_prev_valid_focus ( ) const

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

• void force_drag ( Variant data, Control preview )

通过传递data和preview强制拖动并绕过get_drag_data和set_drag_preview。即使鼠标既不在该控件上，也未在该控件上按下，都将开始拖动。

方法can_drop_data和drop_data必须在要接收放置数据的控件上实现。

• float get_anchor ( Margin margin ) const

从Margin枚举返回由margin常量标识的锚。 anchor_bottom，anchor_left，anchor_right和anchor_top的获取方法。

• Vector2 get_begin ( ) const

返回margin_left和margin_top。另请参阅rect_position。

• Color get_color ( String name, String theme_type=”” ) const

如果该 Theme 具有指定 name 和 theme_type 的颜色项，则从树中第一个匹配的 Theme 返回 Color。如果省略 theme_type，则使用当前控件的类名作为类型。如果类型是类名，则还会按继承顺序检查其父类。

对于当前控件，首先考虑其本地覆盖项，参阅 add_color_override，然后是其分配的 theme。在当前控件之后，考虑每个父控件及其分配的 theme；未分配theme的控件将被跳过。如果在树中找不到匹配的 Theme，则使用自定义项目 Theme和默认的 Theme，参阅 ProjectSettings.gui/theme/custom。

func _ready():
    # 获取为当前控件类定义的字体颜色（如果存在）。
    modulate = get_color("font_color")
    # 获取为 Button 类定义的字体颜色。
    modulate = get_color("font_color", "Button")

• Vector2 get_combined_minimum_size ( ) const

返回rect_min_size和get_minimum_size的组合最小大小。

• int get_constant ( String name, String theme_type=”” ) const

如果该 Theme 具有指定 name 和 theme_type 的常量项目，则从树中的第一个匹配的 Theme 返回常量。

有关详细信息，参阅 get_color。

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

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

• Variant get_drag_data ( Vector2 position ) virtual

Godot调用此方法来获取可以拖放到期望放置数据的控件上的数据。如果没有要拖动的数据，则返回null。想要接收放置数据的控件应实现can_drop_data和drop_data。 position在此控件中是本地的。可以使用force_drag强制拖动。

可以使用set_drag_preview设置跟随鼠标的预览，该预览将代表数据。设置预览的好时机就是这种方法。

func get_drag_data(position):
    var mydata = make_data()
    set_drag_preview(make_preview(mydata))
    return mydata

• Vector2 get_end ( ) const

返回margin_right和margin_bottom。

• NodePath get_focus_neighbour ( Margin margin ) const

返回由Margin枚举的margin常量标识的焦点邻居。 focus_neighbour_bottom，focus_neighbour_left，focus_neighbour_right和focus_neighbour_top的获取方法。

• Control get_focus_owner ( ) const

返回有键盘焦点的控件，如果没有，则返回null。

• Font get_font ( String name, String theme_type=”” ) const

如果该 Theme 具有指定 name 和 theme_type 的字体项目，则从树中第一个匹配的 Theme 返回 Font。

有关详细信息，请参阅 get_color。

• Rect2 get_global_rect ( ) const

返回控件相对于屏幕左上角的位置和大小。请参阅rect_position和rect_size。

• Texture get_icon ( String name, String theme_type=”” ) const

如果该 Theme 具有指定 name 和 theme_type 的图标项目，则从树中第一个匹配的 Theme 返回图标。

有关详细信息，请参阅 get_color。

• float get_margin ( Margin margin ) const

从Margin枚举返回由margin常量标识的锚。 margin_bottom，margin_left，margin_right和margin_top的获取方法。

• Vector2 get_minimum_size ( ) const

返回此控件的最小尺寸。参阅rect_min_size。

• Vector2 get_parent_area_size ( ) const

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

• Control get_parent_control ( ) const

返回父控制节点。

• Rect2 get_rect ( ) const

返回相对于父控件左上角的控件的位置和大小。请参阅rect_position和rect_size。

• float get_rotation ( ) const

返回旋转（以弧度为单位）。

• StyleBox get_stylebox ( String name, String theme_type=”” ) const

返回树中首个符合条件的 Theme 的 StyleBox，这个 Theme 具有名称为 name 并且主题类型为 theme_type 的样式盒。

详情请参阅 get_color。

• Font get_theme_default_font ( ) const

如果 Theme 具有有效的 Theme.default_font 值，则从树中第一个匹配的 Theme 返回默认字体。

有关详细信息，参阅 get_color。

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

返回工具提示，当光标停留在该控件上时将显示该工具提示。请参阅hint_tooltip。

• void grab_click_focus ( )

创建一个InputEventMouseButton，尝试点击控件。如果接收到该事件，控件就会获得焦点。

func _process(delta):
    grab_click_focus() #when clicking another Control node, this node will be clicked instead

• void grab_focus ( )

从另一个控件中窃取焦点，并成为焦点控件（请参阅focus_mode）。

• bool has_color ( String name, String theme_type=”” ) const

如果树中存在匹配的 Theme 且具有指定 name 和 theme_type 的颜色项，则返回 true。

有关详细信息，参阅 get_color。

• bool has_color_override ( String name ) const

如果在此 Control 节点中具有指定 name 的主题颜色 Color 的本地覆盖项，则返回 true。

参阅 add_color_override。

• bool has_constant ( String name, String theme_type=”” ) const

如果树中存在匹配的 Theme 且具有指定 name 和 theme_type 的常量项目，则返回 true。

有关详细信息，参阅 get_color。

• bool has_constant_override ( String name ) const

如果此 Control 节点中具有指定 name 的主题常量存在本地覆盖项，则返回 true。

参阅 add_constant_override。

• bool has_focus ( ) const

如果这是当前的焦点控件，则返回true。参阅focus_mode。

• bool has_font ( String name, String theme_type=”” ) const

如果树中存在 Theme 且该主题具有指定 name 和 theme_type 的字体项目，则返回 true。

详情请参阅 get_color。

• bool has_font_override ( String name ) const

如果在此 Control 节点中具有指定 name 的主题 Font 的本地覆盖项目，则返回 true。

参阅add_font_override。

• bool has_icon ( String name, String theme_type=”” ) const

如果树中存在 Theme 且该主题具有指定 name 和 theme_type 的图标项目，则返回 true。

详情请参阅 get_color。

• bool has_icon_override ( String name ) const

如果此 Control 节点中具有指定 name 的主题图标存在本地覆盖项，则返回 true。

参阅 add_icon_override。

• bool has_point ( Vector2 point ) virtual

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

如果未覆盖，则默认行为是检查该点是否在控件的 Rect 范围内。

注意：如果要检查控件中是否有点，可以使用 get_rect().has_point(point)。

• bool has_shader_override ( String name ) const

如果此 Control 节点中具有指定 name 的主题着色器存在本地覆盖项，则返回 true。

参阅add_shader_override。

• bool has_stylebox ( String name, String theme_type=”” ) const

如果树中存在 Theme 且该主题具有指定 name 和 theme_type 的样式盒项目，则返回 true。

详情请参阅 get_color。

• bool has_stylebox_override ( String name ) const

如果在此 Control 节点中具有指定 name 的主题 StyleBox 的本地覆盖项，则返回 true。

参阅 add_stylebox_override。

• void minimum_size_changed ( )

使此节点和父节点（直至最高级别）中的大小缓存无效。打算在更改返回值时与get_minimum_size一起使用。设置rect_min_size直接直接自动调用此方法。

• void release_focus ( )

放弃焦点。其他控件将无法接收键盘输入。

• void set_anchor ( Margin margin, float anchor, bool keep_margin=false, bool push_opposite_anchor=true )

将由Margin枚举的margin常量标识的锚设置为值anchor。用于anchor_bottom，anchor_left，anchor_right和anchor_top的setter方法。

如果keep_margin为true，则在执行此操作后不会更新边距。

如果push_opposite_anchor为true，并且相对的锚点与该锚点重叠，则相对的锚点将覆盖其值。例如，当将左锚点设置为1且右锚点的值为0.5时，右锚点的值也将为1。如果push_opposite_anchor为false，则左锚点将得到值0.5。

• void set_anchor_and_margin ( Margin margin, float anchor, float offset, bool push_opposite_anchor=false )

与set_anchor的工作原理相同，但是它代替keep_margin参数和边距的自动更新，它允许您自己设置边距偏移量（请参阅set_margin）。

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

设置锚定预设和边距预设。请参阅set_anchors_preset和set_margins_preset。

• void set_anchors_preset ( LayoutPreset preset, bool keep_margins=false )

将锚点设置为预设 preset，取值范围为 LayoutPreset 枚举。等效于在 2D 编辑器中使用布局菜单。

如果 keep_margins 是 true，控件的位置也会更新。

• void set_begin ( Vector2 position )

同时设置margin_left和margin_top。等效于更改rect_position。

• void set_drag_forwarding ( Control target )

将此控件的拖放操作转发到 target 控件。

可以在目标控件中实现转发，类似于方法 get_drag_data、can_drop_data 和 drop_data，但有两个区别：

1. 函数名称必须带有 _fw 后缀

2. 该函数必须接受一个额外的参数，即进行转发的控件

# ThisControl.gd
extends Control
func _ready():
    set_drag_forwarding(target_control)
# TargetControl.gd
extends Control
func can_drop_data_fw(position, data, from_control):
    return true
func drop_data_fw(position, data, from_control):
    my_handle_data(data)
func get_drag_data_fw(position, from_control):
    set_drag_preview(my_preview)
    return my_data()

• void set_drag_preview ( Control control )

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

export (Color, RGBA) var color = Color(1, 0, 0, 1)
func get_drag_data(position):
    # 使用不在树中的控件
    var cpb = ColorPickerButton.new()
    cpb.color = color
    cpb.rect_size = Vector2(50, 50)
    set_drag_preview(cpb)
    return color

• void set_end ( Vector2 position )

同时设置margin_right和margin_bottom。

• void set_focus_neighbour ( Margin margin, NodePath neighbour )

设置由margin常量标识的锚，从Margin枚举到neighbor节点路径处的Control。用于focus_neighbour_bottom，focus_neighbour_left，focus_neighbour_right和focus_neighbour_top的设置方法。

• void set_global_position ( Vector2 position, bool keep_margins=false )

将rect_global_position设置为给定的position。

如果keep_margins为true，则控件的锚点将被更新，而不是边距。

• void set_margin ( Margin margin, float offset )

设置由Margin枚举到offset的margin常量所标识的边距。用于margin_bottom，margin_left，margin_right和margin_top的设置方法。

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

从 LayoutPreset 枚举将边距设置为 preset。这是等效于在 2D 编辑器中使用布局菜单的编码。

使用参数 resize_mode 和 LayoutPresetMode 中的常量来更好地确定 Control 的最终大小。如果与更改大小的预设一起使用，则常规大小将被忽略，例如PRESET_LEFT_WIDE。

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

• void set_position ( Vector2 position, bool keep_margins=false )

将rect_position设置为给定的position。

如果keep_margins为true，则控件的锚点将被更新，而不是边距。

• void set_rotation ( float radians )

设置旋转度（以弧度为单位）。

• void set_size ( Vector2 size, bool keep_margins=false )

设置控件的大小(参阅rect_size)。

如果keep_margins是true，则会更新控件的锚点而不是页边距。

• void show_modal ( bool exclusive=false )

模态显示控件。控件必须是一个子窗口。模态控件捕获输入信号，直到关闭或访问它们之外的区域。当模态控件失去焦点或按下 ESC 键时，会自动隐藏。模态控件广泛用于弹出对话框和菜单。

如果 exclusive 为 true，则其他控件将不会接收输入，并且在此控件外单击不会关闭它。

• void warp_mouse ( Vector2 to_position )

将鼠标光标移动到 to_position，相对于这个控件 Control 的 rect_position。