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

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)

SizeFlags

size_flags_horizontal

1

float

size_flags_stretch_ratio

1.0

SizeFlags

size_flags_vertical

1

Theme

theme

StringName

theme_type_variation

&""

String

tooltip_text

""

Methods

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 const

Vector2

_get_minimum_size ( ) 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

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 )


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 <