This page documents the common GUI control widgets in Godot's scene/gui/ directory: hierarchical trees, flat item lists, numeric spinboxes, range-based controls, popup menus, and tabbed containers. It covers their class structure, internal data models, input handling, and key APIs.
For the foundational Control class (anchors, layout, theming, focus), see 4.4 For text editing controls (TextEdit, CodeEdit, RichTextLabel, Label, LineEdit), see 11
The controls documented here all inherit from Control, which itself extends CanvasItem → Node → Object.
Class hierarchy diagram
Sources: scene/gui/base_button.h48-110 scene/gui/tree.h48-350 scene/gui/item_list.h31-180 scene/gui/popup_menu.h105-280 scene/gui/spin_box.h31-100 scene/gui/tab_container.h35-150 scene/gui/color_picker.h31-100
Range is the abstract base class for any control whose value is constrained within a numeric interval. All concrete range widgets (SpinBox, HSlider, VSlider, HScrollBar, VScrollBar, ProgressBar) inherit from it.
| Property | Description |
|---|---|
min_value | Minimum allowed value |
max_value | Maximum allowed value |
step | Increment unit (0 = continuous) |
value | Current value, clamped to [min, max] |
ratio | Normalized position (value - min) / (max - min) |
exp_edit | Whether editing uses exponential scaling |
allow_greater / allow_lesser | Permit values outside the declared range |
Multiple Range controls can be linked via Range::share(). Linked controls maintain the same internal Shared data structure, so changing one updates all peers. This is used by SpinBox to sync its embedded LineEdit display with the slider value.
Sources: scene/gui/range.cpp31-150 scene/gui/spin_box.cpp83-115
SpinBox is a Range subclass that presents a LineEdit for direct text entry plus up/down increment buttons drawn on the right side.
SpinBox Internal Components
SpinBoxLineEdit, a private subclass of LineEdit. It exposes accessibility increment/decrement actions._update_text() scene/gui/spin_box.cpp89-115 formats the current value with prefix, suffix, and optional numeral-system localization via TranslationServer._text_submitted() scene/gui/spin_box.cpp117-140 parses the text using Godot's Expression evaluator, allowing the user to type arithmetic expressions like 2+3.Sources: scene/gui/spin_box.cpp31-250 scene/gui/spin_box.h31-60
BaseButton is the abstract parent for all clickable controls. It does not render itself; subclasses implement drawing.
When toggle_mode is enabled, press events flip status.pressed instead of momentarily activating. ButtonGroup enforces mutual exclusion: pressing one button in the group calls _unpress_group(), which iterates button_group->buttons and calls set_pressed(false) on all others scene/gui/base_button.cpp41-58
BaseButton::gui_input() scene/gui/base_button.cpp60-116 manages the interaction state:
status.touch_index for multi-touch support scene/gui/base_button.cpp73-86status.pressing_inside by checking has_point(position) during mouse/touch motion scene/gui/base_button.cpp91-96on_action_event() when the appropriate mouse button (defined by button_mask) is pressed or released scene/gui/base_button.cpp104Sources: scene/gui/base_button.cpp31-210 scene/gui/base_button.h31-110
PopupMenu renders a vertical list of Item entries. It inherits from Popup, which is a specialized Window.
Each entry is a PopupMenu::Item struct scene/gui/popup_menu.h48-102:
text / xl_text: Raw and translated display text.checkable_type: None, checkbox, or radio button scene/gui/popup_menu.cpp69-81accel: Direct key accelerator.submenu: Nested PopupMenu*.When NativeMenu::FEATURE_POPUP_MENU is supported, bind_global_menu() scene/gui/popup_menu.cpp88-188 registers the item list with the OS. This allows the menu to appear in the system global menu bar (e.g., macOS top bar). It maps Godot's Callable activation to native menu callbacks scene/gui/popup_menu.cpp125
PopupMenu Activation Flow
Sources: scene/gui/popup_menu.cpp31-250 scene/gui/popup_menu.h31-150
Tree displays hierarchically organized data. TreeItem represents a row and is an Object managed by the Tree.
Each TreeItem holds a Vector<Cell> scene/gui/tree.h143 The number of cells matches the number of columns in the Tree. Items are unlinked from the tree via _unlink_from_tree() scene/gui/tree.h189-205 which also frees accessibility elements.
Tree Hierarchical Data Model
Set with TreeItem::set_cell_mode(column, mode) scene/gui/tree.cpp191-212:
CELL_MODE_STRING: Text editing.CELL_MODE_CHECK: Checkbox logic.CELL_MODE_RANGE: Numeric sliders/dropdowns.CELL_MODE_ICON: Only an icon.CELL_MODE_CUSTOM: Uses custom_draw_callback.Sources: scene/gui/tree.cpp31-212 scene/gui/tree.h48-250
ItemList is a flat scrollable list of items with icons and text.
ItemList uses _shape_text(index) scene/gui/item_list.cpp41-59 to prepare text for rendering. It configures the text_buf with direction (LTR/RTL), language locale, and break flags based on icon_mode scene/gui/item_list.cpp52-56
The add_item scene/gui/item_list.cpp61-77 and add_icon_item scene/gui/item_list.cpp79-91 functions return the index of the newly created item. Tooltips can be toggled per-item via set_item_tooltip_enabled scene/gui/item_list.cpp172-182
Sources: scene/gui/item_list.cpp31-182 scene/gui/item_list.h31-120
ColorPicker is a control for selecting colors, offering various modes (e.g., HSV, RGB) and a color palette.
The ColorPicker internally manages a Color value. It supports overbright colors and provides utility functions like is_color_overbright() scene/gui/color_picker.cpp69-71 and color_to_string() scene/gui/color_picker.cpp77-88 for conversion.
The ColorPicker can pick colors directly from the screen.
DisplayServer::FEATURE_NATIVE_COLOR_PICKER is available, it uses _pick_button_pressed_native() scene/gui/color_picker.cpp113-115DisplayServer::FEATURE_SCREEN_CAPTURE is available, it uses _pick_button_pressed() scene/gui/color_picker.cpp116-119_pick_button_pressed_legacy() scene/gui/color_picker.cpp121-124 which picks from the application window.The appearance of the ColorPicker is heavily influenced by the theme. NOTIFICATION_THEME_CHANGED scene/gui/color_picker.cpp127-160 updates icons, button sizes, and shape popups.
Sources: scene/gui/color_picker.cpp31-160 scene/gui/color_picker.h31-100
TabBar manages the visual tabs themselves without the content panels. Its get_minimum_size() logic accounts for tab_unselected_style, icons, text, and optional close buttons.
TabContainer pairs a TabBar with content panels (child nodes).
_notification(NOTIFICATION_DRAW) scene/gui/tab_container.cpp157-173 draws the panel_style for the content area and the tabbar_style background for the header._as_tab_control() scene/gui/tab_container.cpp59-65 filters out internal components like the internal container or children currently being removed.Sources: scene/gui/tab_container.cpp31-173 scene/gui/tab_container.h35-150
ScrollContainer is a container that provides scrollbars for its content when it exceeds the container's bounds.
_get_margins() scene/gui/scroll_container.cpp146-155 calculates margins based on the panel_style and optional focus_style._get_minimum_size() scene/gui/scroll_container.cpp43-94 iterates through children to find the largest minimum size and adds space for scrollbars based on horizontal_scroll_mode and vertical_scroll_mode._cancel_drag() scene/gui/scroll_container.cpp121-135 resets the internal drag state, including speed and accumulation._is_h_scroll_visible() scene/gui/scroll_container.cpp137-140 and _is_v_scroll_visible() scene/gui/scroll_container.cpp142-144 determine if scrollbars are currently active and parented to the container.Sources: scene/gui/scroll_container.cpp31-155 scene/gui/scroll_container.h31-120
OptionButton is a button that pops up a PopupMenu when pressed, allowing the user to select one of several items.
get_minimum_size() scene/gui/option_button.cpp55-80 calculates size based on the longest item if fit_to_longest_item is enabled, and adds space for the "arrow" icon._notification(NOTIFICATION_DRAW) scene/gui/option_button.cpp103-142 renders the arrow icon, modulating its color based on the current draw mode (hover, pressed, etc.)._select() scene/gui/option_button.cpp198-200 updates the internal selection index and refreshes the button's display text and icon.Sources: scene/gui/option_button.cpp31-200 scene/gui/option_button.h31-100
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.