Up to date

This page is up to date for Godot 4.2. 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

Base class for all GUI controls. Adapts its position and size based on its parent control.

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)

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

""

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

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