Up to date
This page is up to date for Godot 4.0.
If you still find outdated information, please open an issue.
Control¶
Inherits: CanvasItem < Node < Object
Inherited By: BaseButton, ColorRect, Container, GraphEdit, ItemList, Label, LineEdit, MenuBar, NinePatchRect, Panel, Range, ReferenceRect, RichTextLabel, Separator, TabBar, TextEdit, TextureRect, Tree, VideoStreamPlayer
All user interface nodes inherit from Control. A control's anchors and offsets adapt its position and size relative to its parent.
Description¶
Base class for all UI-related nodes. Control features a bounding rectangle that defines its extents, an anchor position relative to its parent control or the current viewport, and offsets relative to the anchor. The offsets update automatically when the node, any of its parents, or the screen size change.
For more information on Godot's UI system, anchors, offsets, and containers, see the related tutorials in the manual. To build flexible UIs, you'll need a mix of UI elements that inherit from Control and Container nodes.
User Interface nodes and input
Godot propagates input events via viewports. Each Viewport is responsible for propagating InputEvents to their child nodes. As the SceneTree.root is a Window, this already happens automatically for all UI elements in your game.
Input events are propagated through the SceneTree from the root node to all child nodes by calling Node._input. For UI elements specifically, it makes more sense to override the virtual method _gui_input, which filters out unrelated input events, such as by checking z-order, mouse_filter, focus, or if the event was inside of the control's bounding box.
Call accept_event so no other node receives the event. Once you accept an input, it becomes handled so Node._unhandled_input will not process it.
Only one Control node can be in focus. Only the node in focus will receive events. To get the focus, call grab_focus. Control nodes lose focus when another node grabs it, or if you hide the node in focus.
Sets mouse_filter to MOUSE_FILTER_IGNORE to tell a Control node to ignore mouse or touch events. You'll need it if you place an icon on top of a button.
Theme resources change the Control's appearance. If you change the Theme on a Control node, it affects all of its children. To override some of the theme's parameters, call one of the add_theme_*_override methods, like add_theme_font_override. You can override the theme with the Inspector.
Note: Theme items are not Object properties. This means you can't access their values using Object.get and Object.set. Instead, use the get_theme_* and add_theme_*_override methods provided by this class.
Tutorials¶
Properties¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Methods¶
Signals¶
focus_entered ( )
Emitted when the node gains focus.
focus_exited ( )
Emitted when the node loses focus.
gui_input ( InputEvent event )
Emitted when the node receives an InputEvent.
minimum_size_changed ( )
Emitted when the node's minimum size changes.
mouse_entered ( )
Emitted when the mouse enters the control's Rect area, provided its mouse_filter lets the event reach it.
Note: mouse_entered will not be emitted if the mouse enters a child Control node before entering the parent's Rect area, at least until the mouse is moved to reach the parent's Rect area.
mouse_exited ( )
Emitted when the mouse leaves the control's Rect area, provided its mouse_filter lets the event reach it.
Note: mouse_exited will be emitted if the mouse enters a child Control node, even if the mouse cursor is still inside the parent's Rect area.
If you want to check whether the mouse truly left the area, ignoring any top nodes, you can use code like this:
func _on_mouse_exited():
if not Rect2(Vector2(), size).has_point(get_local_mouse_position()):
# Not hovering over area.
resized ( )
Emitted when the control changes size.
size_flags_changed ( )
Emitted when one of the size flags changes. See size_flags_horizontal and size_flags_vertical.
theme_changed ( )
Emitted when the NOTIFICATION_THEME_CHANGED notification is sent.
Enumerations¶
enum FocusMode:
FocusMode FOCUS_NONE = 0
The node cannot grab focus. Use with focus_mode.
FocusMode FOCUS_CLICK = 1
The node can only grab focus on mouse clicks. Use with focus_mode.
FocusMode FOCUS_ALL = 2
The node can grab focus on mouse click, using the arrows and the Tab keys on the keyboard, or using the D-pad buttons on a gamepad. Use with focus_mode.
enum CursorShape:
CursorShape CURSOR_ARROW = 0
Show the system's arrow mouse cursor when the user hovers the node. Use with mouse_default_cursor_shape.
CursorShape CURSOR_IBEAM = 1
Show the system's I-beam mouse cursor when the user hovers the node. The I-beam pointer has a shape similar to "I". It tells the user they can highlight or insert text.
CursorShape CURSOR_POINTING_HAND = 2
Show the system's pointing hand mouse cursor when the user hovers the node.
CursorShape CURSOR_CROSS = 3
Show the system's cross mouse cursor when the user hovers the node.
CursorShape CURSOR_WAIT = 4
Show the system's wait mouse cursor when the user hovers the node. Often an hourglass.
CursorShape CURSOR_BUSY = 5
Show the system's busy mouse cursor when the user hovers the node. Often an arrow with a small hourglass.
CursorShape CURSOR_DRAG = 6
Show the system's drag mouse cursor, often a closed fist or a cross symbol, when the user hovers the node. It tells the user they're currently dragging an item, like a node in the Scene dock.
CursorShape CURSOR_CAN_DROP = 7
Show the system's drop mouse cursor when the user hovers the node. It can be an open hand. It tells the user they can drop an item they're currently grabbing, like a node in the Scene dock.
CursorShape CURSOR_FORBIDDEN = 8
Show the system's forbidden mouse cursor when the user hovers the node. Often a crossed circle.
CursorShape CURSOR_VSIZE = 9
Show the system's vertical resize mouse cursor when the user hovers the node. A double-headed vertical arrow. It tells the user they can resize the window or the panel vertically.
CursorShape CURSOR_HSIZE = 10
Show the system's horizontal resize mouse cursor when the user hovers the node. A double-headed horizontal arrow. It tells the user they can resize the window or the panel horizontally.
CursorShape CURSOR_BDIAGSIZE = 11
Show the system's window resize mouse cursor when the user hovers the node. The cursor is a double-headed arrow that goes from the bottom left to the top right. It tells the user they can resize the window or the panel both horizontally and vertically.
CursorShape CURSOR_FDIAGSIZE = 12
Show the system's window resize mouse cursor when the user hovers the node. The cursor is a double-headed arrow that goes from the top left to the bottom right, the opposite of CURSOR_BDIAGSIZE. It tells the user they can resize the window or the panel both horizontally and vertically.
CursorShape CURSOR_MOVE = 13
Show the system's move mouse cursor when the user hovers the node. It shows 2 double-headed arrows at a 90 degree angle. It tells the user they can move a UI element freely.
CursorShape CURSOR_VSPLIT = 14
Show the system's vertical split mouse cursor when the user hovers the node. On Windows, it's the same as CURSOR_VSIZE.
CursorShape CURSOR_HSPLIT = 15
Show the system's horizontal split mouse cursor when the user hovers the node. On Windows, it's the same as CURSOR_HSIZE.
CursorShape CURSOR_HELP = 16
Show the system's help mouse cursor when the user hovers the node, a question mark.
enum LayoutPreset:
LayoutPreset PRESET_TOP_LEFT = 0
Snap all 4 anchors to the top-left of the parent control's bounds. Use with set_anchors_preset.
LayoutPreset PRESET_TOP_RIGHT = 1
Snap all 4 anchors to the top-right of the parent control's bounds. Use with set_anchors_preset.
LayoutPreset PRESET_BOTTOM_LEFT = 2
Snap all 4 anchors to the bottom-left of the parent control's bounds. Use with set_anchors_preset.
LayoutPreset PRESET_BOTTOM_RIGHT = 3
Snap all 4 anchors to the bottom-right of the parent control's bounds. Use with set_anchors_preset.
LayoutPreset PRESET_CENTER_LEFT = 4
Snap all 4 anchors to the center of the left edge of the parent control's bounds. Use with set_anchors_preset.
LayoutPreset PRESET_CENTER_TOP = 5
Snap all 4 anchors to the center of the top edge of the parent control's bounds. Use with set_anchors_preset.
LayoutPreset PRESET_CENTER_RIGHT = 6
Snap all 4 anchors to the center of the right edge of the parent control's bounds. Use with set_anchors_preset.
LayoutPreset PRESET_CENTER_BOTTOM = 7
Snap all 4 anchors to the center of the bottom edge of the parent control's bounds. Use with set_anchors_preset.
LayoutPreset PRESET_CENTER = 8
Snap all 4 anchors to the center of the parent control's bounds. Use with set_anchors_preset.
LayoutPreset PRESET_LEFT_WIDE = 9
Snap all 4 anchors to the left edge of the parent control. The left offset becomes relative to the left edge and the top offset relative to the top left corner of the node's parent. Use with <