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

<