This document covers Godot's UI system built around the Control class, including layout management, input handling, theming, and integration with the viewport system. For information about viewport rendering and canvas transforms, see Viewport System. For window management and native window integration, see Window Management.
The Control & UI System provides a comprehensive framework for building user interfaces in Godot. It defines how UI elements position and size themselves, handle user input, apply visual themes, and interact with the scene tree. The system is anchored by the Control class, which all GUI nodes inherit from scene/gui/control.h40
Core class relationships in the UI system
Sources: scene/gui/control.h40-41 scene/main/viewport.h425-604 scene/main/node.h54-128 doc/classes/Control.xml2-18 scene/main/window.h116-120
The Control layout system determines how UI elements position and size themselves relative to their parent control or viewport. There are four primary layout modes defined in LayoutMode scene/gui/control.h149-154:
| Layout Mode | Description | Use Case |
|---|---|---|
LAYOUT_MODE_POSITION | Uses position and size properties directly | Manual positioning |
LAYOUT_MODE_ANCHORS | Uses anchor points and offsets | Responsive layouts |
LAYOUT_MODE_CONTAINER | Managed by parent Container node | Automatic layouts |
LAYOUT_MODE_UNCONTROLLED | No automatic layout management | Advanced custom control |
Sources: scene/gui/control.h149-154
How anchors and offsets determine control position and trigger notifications
Sources: scene/gui/control.cpp119-152 scene/gui/control.h55-58
The anchor system allows controls to maintain relative positions when their parent resizes. Each side (left, top, right, bottom) has an anchor value between 0.0 and 1.0, representing a percentage of the parent's size, plus a pixel offset scene/gui/control.h55-58
Sources: scene/gui/control.cpp140-149 scene/gui/control.h55-58
When a Control is a child of a Container node, the container manages its layout using size flags scene/gui/control.h79-87:
| Size Flag | Value | Description |
|---|---|---|
SIZE_SHRINK_BEGIN | 0 | Align to start |
SIZE_FILL | 1 | Fill available space |
SIZE_EXPAND | 2 | Request extra space when available |
SIZE_SHRINK_CENTER | 4 | Shrink and center |
SIZE_SHRINK_END | 8 | Shrink and align to end |
Sources: scene/gui/control.h79-87
Container nodes read these flags and set the child's position and size accordingly. The layout mode automatically becomes LAYOUT_MODE_CONTAINER when the control is added to a container scene/gui/control.h152
Sources: scene/gui/control.h152 doc/classes/Control.xml7-8
Input event flow from DisplayServer to Control
Sources: scene/main/viewport.cpp215-220 scene/main/node.cpp171-180
The viewport maintains GUI state in the Gui struct for input handling scene/main/viewport.h510:
Key methods that operate on this state:
_gui_call_input(Control*, InputEvent) - Dispatch input to control.gui_get_focus_owner() - Returns gui.key_focus.accept_event() - Sets gui.key_event_accepted = true.Sources: scene/main/viewport.h510-604 doc/classes/Control.xml11-13
Controls can filter mouse events using the MouseFilter enum scene/gui/control.h89-93:
| Mode | Behavior |
|---|---|
MOUSE_FILTER_STOP | Receives and stops mouse events |
MOUSE_FILTER_PASS | Receives events but passes them through |
MOUSE_FILTER_IGNORE | Ignores all mouse events |
Sources: scene/gui/control.h89-93
The focus system determines which control receives keyboard input. Focus is managed by the viewport doc/classes/Control.xml14:
Focus mode determines how a control can receive keyboard focus
Sources: scene/gui/control.h66-71 doc/classes/Control.xml14 scene/main/viewport.h512
Key focus methods:
grab_focus() - Request keyboard focus doc/classes/Control.xml14release_focus() - Release keyboard focus.has_focus() - Check if control has focus.Sources: doc/classes/Control.xml14 scene/gui/control.h66-71
The theming system provides visual customization through a hierarchical override system. Controls and Windows can override theme properties locally scene/gui/control.h234-245
The theming system supports several data types managed via theme_override_* properties scene/main/window.cpp63-132:
| Type | Storage (Control::Data) | Window Storage |
|---|---|---|
COLOR | theme_color_override | theme_color_override |
CONSTANT | theme_constant_override | theme_constant_override |
FONT | theme_font_override | theme_font_override |
FONT_SIZE | theme_font_size_override | theme_font_size_override |
ICON | theme_icon_override | theme_icon_override |
STYLEBOX | theme_style_override | theme_style_override |
Sources: scene/gui/control.h234-245 scene/main/window.cpp63-132
When theme properties change, nodes are notified through NOTIFICATION_THEME_CHANGED scene/gui/control.cpp151 The engine ensures that theme changes propagate through the hierarchy to maintain visual consistency.
Sources: scene/gui/control.h234-245 scene/gui/control.cpp151
The Control class provides virtual methods for drag and drop operations. The Viewport manages drag state in gui.drag_data and gui.drag_preview scene/main/viewport.h544-545
| Method | Purpose |
|---|---|
_get_drag_data(pos) | Provide data to drag doc/classes/Control.xml103 |
_can_drop_data(pos, data) | Validate if drop is allowed doc/classes/Control.xml33 |
_drop_data(pos, data) | Handle the drop operation doc/classes/Control.xml59 |
Sources: doc/classes/Control.xml33-105 scene/main/viewport.h544-545
The UI system integrates with the AccessibilityServer to support screen readers. Nodes receive NOTIFICATION_ACCESSIBILITY_UPDATE when accessibility information needs to be refreshed scene/main/node.cpp77
Sources: scene/main/node.cpp77-97
| Class | File | Primary Responsibilities |
|---|---|---|
Control | scene/gui/control.cpp | Base UI class, layout, theming, input dispatch |
Viewport | scene/main/viewport.cpp | GUI state management, hit testing, event routing |
Window | scene/main/window.cpp | Top-level UI surface, multi-window theme management |
SceneTree | scene/main/scene_tree.cpp | Group management for input propagation |
TextEdit | scene/gui/text_edit.cpp | Complex multi-line text editing and rendering |
Tree | scene/gui/tree.cpp | Hierarchical list/tree data display and editing |
Sources: scene/gui/control.h40-41 scene/main/viewport.h425-604 scene/main/node.h54-128 scene/main/window.h116-120 scene/gui/text_edit.h40 scene/gui/tree.h322
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.