Control

Inherits: CanvasItem < Node < Object

Inherited By: Label, Tabs, TextureFrame, ButtonArray, VideoPlayer, LineEdit, ColorFrame, Container, ReferenceFrame, Patch9Frame, TextEdit, BaseButton, Popup, Tree, Separator, Panel, TabContainer, Range, RichTextLabel, GraphEdit, ItemList

Category: Core

Brief Description

Control is the base node for all the GUI components.

Member Functions

void _input_event ( InputEvent event ) virtual
void accept_event ( )
void add_color_override ( String name, Color color )
void add_constant_override ( String name, int constant )
void add_font_override ( String name, Font font )
void add_icon_override ( String name, Texture texture )
void add_shader_override ( String name, Shader shader )
void add_style_override ( String name, StyleBox stylebox )
bool can_drop_data ( Vector2 pos, Variant data ) virtual
void drop_data ( Vector2 pos, Variant data ) virtual
void force_drag ( Variant data, Object preview )
int get_anchor ( int margin ) const
Vector2 get_begin ( ) const
Color get_color ( String name, String type=”” ) const
Vector2 get_combined_minimum_size ( ) const
int get_constant ( String name, String type=”” ) const
int get_cursor_shape ( Vector2 pos=Vector2(0, 0) ) const
Vector2 get_custom_minimum_size ( ) const
int get_default_cursor_shape ( ) const
Object get_drag_data ( Vector2 pos ) virtual
Vector2 get_end ( ) const
int get_focus_mode ( ) const
NodePath get_focus_neighbour ( int margin ) const
Control get_focus_owner ( ) const
Font get_font ( String name, String type=”” ) const
Vector2 get_global_pos ( ) const
Rect2 get_global_rect ( ) const
int get_h_size_flags ( ) const
Texture get_icon ( String name, String type=”” ) const
float get_margin ( int margin ) const
Vector2 get_minimum_size ( ) const
Vector2 get_minimum_size ( ) virtual
Vector2 get_parent_area_size ( ) const
Control get_parent_control ( ) const
Vector2 get_pos ( ) const
Rect2 get_rect ( ) const
float get_rotation ( ) const
float get_rotation_deg ( ) const
Vector2 get_scale ( ) const
Vector2 get_size ( ) const
float get_stretch_ratio ( ) const
StyleBox get_stylebox ( String name, String type=”” ) const
Theme get_theme ( ) const
String get_tooltip ( Vector2 atpos=Vector2(0, 0) ) const
int get_v_size_flags ( ) const
void grab_click_focus ( )
void grab_focus ( )
bool has_color ( String name, String type=”” ) const
bool has_color_override ( String name ) const
bool has_constant ( String name, String type=”” ) const
bool has_constant_override ( String name ) const
bool has_focus ( ) const
bool has_font ( String name, String type=”” ) const
bool has_font_override ( String name ) const
bool has_icon ( String name, String type=”” ) const
bool has_icon_override ( String name ) const
void has_point ( Vector2 point ) virtual
bool has_stylebox ( String name, String type=”” ) const
bool has_stylebox_override ( String name ) const
bool is_ignoring_mouse ( ) const
bool is_stopping_mouse ( ) const
void minimum_size_changed ( )
void release_focus ( )
void set_anchor ( int margin, int anchor_mode, bool keep_margin=false )
void set_anchor_and_margin ( int margin, int anchor_mode, float offset )
void set_area_as_parent_rect ( int margin=0 )
void set_begin ( Vector2 pos )
void set_custom_minimum_size ( Vector2 size )
void set_default_cursor_shape ( int shape )
void set_drag_forwarding ( Control target )
void set_drag_preview ( Control control )
void set_end ( Vector2 pos )
void set_focus_mode ( int mode )
void set_focus_neighbour ( int margin, NodePath neighbour )
void set_global_pos ( Vector2 pos )
void set_h_size_flags ( int flags )
void set_ignore_mouse ( bool ignore )
void set_margin ( int margin, float offset )
void set_pos ( Vector2 pos )
void set_rotation ( float radians )
void set_rotation_deg ( float degrees )
void set_scale ( Vector2 scale )
void set_size ( Vector2 size )
void set_stop_mouse ( bool stop )
void set_stretch_ratio ( float ratio )
void set_theme ( Theme theme )
void set_tooltip ( String tooltip )
void set_v_size_flags ( int flags )
void show_modal ( bool exclusive=false )
void warp_mouse ( Vector2 to_pos )

Signals

  • focus_enter ( )

Emitted when keyboard focus is gained.

  • focus_exit ( )

Emitted when the keyboard focus is lost.

Emitted when an input event is received. Connecting in realtime is recommended for accepting the events.

  • minimum_size_changed ( )

Emitted when the minimum size of the control changed.

  • modal_close ( )
  • mouse_enter ( )

Emitted when the mouse enters the control area.

  • mouse_exit ( )

Emitted when the mouse left the control area.

  • resized ( )

Emitted when the control changed size.

  • size_flags_changed ( )

Emitted when the size flags changed.

Numeric Constants

  • FOCUS_NONE = 0 — Control can’t acquire focus.
  • FOCUS_CLICK = 1 — Control can acquire focus only if clicked.
  • FOCUS_ALL = 2 — Control can acquire focus if clicked, or by pressing TAB/Directionals in the keyboard from another Control.
  • NOTIFICATION_RESIZED = 40 — Control changed size (get_size() reports the new size).
  • NOTIFICATION_MOUSE_ENTER = 41 — Mouse pointer entered the area of the Control.
  • NOTIFICATION_MOUSE_EXIT = 42 — Mouse pointer exited the area of the Control.
  • NOTIFICATION_FOCUS_ENTER = 43 — Control gained focus.
  • NOTIFICATION_FOCUS_EXIT = 44 — Control lost focus.
  • NOTIFICATION_THEME_CHANGED = 45 — Theme changed. Redrawing is desired.
  • NOTIFICATION_MODAL_CLOSE = 46 — Modal control was closed.
  • CURSOR_ARROW = 0
  • CURSOR_IBEAM = 1
  • CURSOR_POINTING_HAND = 2
  • CURSOR_CROSS = 3
  • CURSOR_WAIT = 4
  • CURSOR_BUSY = 5
  • CURSOR_DRAG = 6
  • CURSOR_CAN_DROP = 7
  • CURSOR_FORBIDDEN = 8
  • CURSOR_VSIZE = 9
  • CURSOR_HSIZE = 10
  • CURSOR_BDIAGSIZE = 11
  • CURSOR_FDIAGSIZE = 12
  • CURSOR_MOVE = 13
  • CURSOR_VSPLIT = 14
  • CURSOR_HSPLIT = 15
  • CURSOR_HELP = 16
  • PRESET_TOP_LEFT = 0
  • PRESET_TOP_RIGHT = 1
  • PRESET_BOTTOM_LEFT = 2
  • PRESET_BOTTOM_RIGHT = 3
  • PRESET_CENTER_LEFT = 4
  • PRESET_CENTER_TOP = 5
  • PRESET_CENTER_RIGHT = 6
  • PRESET_CENTER_BOTTOM = 7
  • PRESET_CENTER = 8
  • PRESET_LEFT_WIDE = 9
  • PRESET_TOP_WIDE = 10
  • PRESET_RIGHT_WIDE = 11
  • PRESET_BOTTOM_WIDE = 12
  • PRESET_VCENTER_WIDE = 13
  • PRESET_HCENTER_WIDE = 14
  • PRESET_WIDE = 15
  • SIZE_EXPAND = 2
  • SIZE_FILL = 1
  • SIZE_EXPAND_FILL = 3
  • SIZE_SHRINK_CENTER = 4
  • SIZE_SHRINK_END = 8
  • MOUSE_FILTER_STOP = 0
  • MOUSE_FILTER_PASS = 1
  • MOUSE_FILTER_IGNORE = 2
  • GROW_DIRECTION_BEGIN = 0
  • GROW_DIRECTION_END = 1
  • ANCHOR_BEGIN = 0 — X is relative to MARGIN_LEFT, Y is relative to MARGIN_TOP.
  • ANCHOR_END = 1 — X is relative to -MARGIN_RIGHT, Y is relative to -MARGIN_BOTTOM.

Description

Control is the base class Node for all the GUI components. Every GUI component inherits from it, directly or indirectly. In this way, sections of the scene tree made of contiguous control nodes, become user interfaces.

Controls are relative to the parent position and size by using anchors and margins. This ensures that they can adapt easily in most situation to changing dialog and screen sizes. When more flexibility is desired, Container derived nodes can be used.

Anchors work by defining which margin do they follow, and a value relative to it. Allowed anchoring modes are ANCHOR_BEGIN, where the margin is relative to the top or left margins of the parent (in pixels), ANCHOR_END for the right and bottom margins of the parent and ANCHOR_RATIO, which is a ratio from 0 to 1 in the parent range.

Input device events are first sent to the root controls via the Node._input, which distribute it through the tree, then delivers them to the adequate one (under cursor or keyboard focus based) by calling MainLoop._input_event. There is no need to enable input processing on controls to receive such events. To ensure that no one else will receive the event (not even Node._unhandled_input), the control can accept it by calling accept_event.

Only one control can hold the keyboard focus (receiving keyboard events), for that the control must define the focus mode with set_focus_mode. Focus is lost when another control gains it, or the current focus owner is hidden.

It is sometimes desired for a control to ignore mouse/pointer events. This is often the case when placing other controls on top of a button, in such cases. Calling set_ignore_mouse enables this function.

Finally, controls are skinned according to a Theme. Setting a Theme on a control will propagate all the skinning down the tree. Optionally, skinning can be overridden per each control by calling the add_*_override functions, or from the editor.

Member Function Description

  • Vector2 _get_minimum_size ( ) virtual

Return the minimum size this Control can shrink to. A control will never be displayed or resized smaller than its minimum size.

  • void accept_event ( )

Handles the event, no other control will receive it and it will not be sent to nodes waiting on Node._unhandled_input or Node._unhandled_key_input.

  • void add_constant_override ( String name, int constant )

Override a single constant (integer) in the theme of this Control. If constant equals Theme.INVALID_CONSTANT, override is cleared.

  • void add_font_override ( String name, Font font )

Override a single font (font) in the theme of this Control. If font is empty, override is cleared.

Override a single icon (Texture) in the theme of this Control. If texture is empty, override is cleared.

Override a single stylebox (Stylebox) in the theme of this Control. If stylebox is empty, override is cleared.

Return the anchor type (ANCHOR_BEGIN, ANCHOR_END, ANCHOR_RATIO) for a given margin (MARGIN_LEFT, MARGIN_TOP, MARGIN_RIGHT, MARGIN_BOTTOM).

  • Vector2 get_combined_minimum_size ( ) const
  • int get_cursor_shape ( Vector2 pos=Vector2( 0, 0 ) ) const

Return the cursor shape at a certain position in the control.

  • Vector2 get_custom_minimum_size ( ) const
  • int get_default_cursor_shape ( ) const

Return the default cursor shape for this control. See enum CURSOR_* for the list of shapes.

Returns MARGIN_LEFT and MARGIN_TOP at the same time. This is a helper (see set_margin).

  • int get_focus_mode ( ) const

Returns the focus access mode for the control (FOCUS_NONE, FOCUS_CLICK, FOCUS_ALL) (see set_focus_mode).

Return the forced neighbour for moving the input focus to. When pressing TAB or directional/joypad directions focus is moved to the next control in that direction. However, the neighbour to move to can be forced with this function.

  • Control get_focus_owner ( ) const

Return which control is owning the keyboard focus, or null if no one.

  • Vector2 get_global_position ( ) const

Returns the Control position, relative to the top-left corner of the parent Control and independent of the anchor mode.

  • Rect2 get_global_rect ( ) const

Return position and size of the Control, relative to the top-left corner of the window Control. This is a helper (see get_global_position, get_size).

  • int get_h_grow_direction ( ) const
  • int get_h_size_flags ( ) const

Hint for containers, return horizontal positioning flags.

Return a margin offset. Margin can be one of (MARGIN_LEFT, MARGIN_TOP, MARGIN_RIGHT, MARGIN_BOTTOM). Offset value being returned depends on the anchor mode.

  • Vector2 get_minimum_size ( ) const

Return the minimum size this Control can shrink to. A control will never be displayed or resized smaller than its minimum size.

  • int get_mouse_filter ( ) const

Return when the control is ignoring mouse events (even touchpad events send mouse events).

  • Vector2 get_parent_area_size ( ) const
  • Control get_parent_control ( ) const
  • Vector2 get_pivot_offset ( ) const

Returns the Control position, relative to the top-left corner of the parent Control and independent of the anchor mode.

  • Rect2 get_rect ( ) const

Return position and size of the Control, relative to the top-left corner of the parent Control. This is a helper (see get_position, get_size).

  • float get_rotation ( ) const

Return the rotation (in radians)

  • float get_rotation_deg ( ) const

Return the rotation (in degrees)

Returns the size of the Control, computed from all margins, however the size returned will never be smaller than the minimum size reported by get_minimum_size. This means that even if end position of the Control rectangle is smaller than the begin position, the Control will still display and interact correctly. (see description, get_minimum_size, set_margin, set_anchor).

  • float get_stretch_ratio ( ) const

Hint for containers, return the stretch ratio. This value is relative to other stretch ratio, so if this control has 2 and another has 1, this one will be twice as big.

  • Theme get_theme ( ) const

Return a Theme override, if one exists (see set_theme).

Return the tooltip, which will appear when the cursor is resting over this control.

  • int get_v_grow_direction ( ) const
  • int get_v_size_flags ( ) const

Hint for containers, return vertical positioning flags.

  • void grab_click_focus ( )
  • void grab_focus ( )

Steal the focus from another control and become the focused control (see set_focus_mode).

  • bool has_constant_override ( String name ) const
  • bool has_focus ( ) const

Return whether the Control is the current focused control (see set_focus_mode).

  • void has_point ( Vector2 point ) virtual
  • bool has_stylebox_override ( String name ) const
  • bool is_clipping_contents ( )
  • void minimum_size_changed ( )
  • void release_focus ( )

Give up the focus, no other control will be able to receive keyboard input.

  • void set_anchor ( int margin, float anchor, bool keep_margin=null, bool push_opposite_anchor=null )
  • void set_anchor_and_margin ( int margin, float anchor, float offset, bool push_opposite_anchor=null )
  • void set_anchors_preset ( int preset, bool keep_margin=null )
  • void set_area_as_parent_rect ( int margin=0 )

Change all margins and anchors, so this Control always takes up the same area as the parent Control. This is a helper (see set_anchor, set_margin).

Sets MARGIN_LEFT and MARGIN_TOP at the same time. This is a helper (see set_margin).

  • void set_clip_contents ( bool enable )
  • void set_custom_minimum_size ( Vector2 size )
  • void set_default_cursor_shape ( int shape )

Set the default cursor shape for this control. See enum CURSOR_* for the list of shapes.

  • void set_drag_forwarding ( Control target )
  • void set_drag_preview ( Control control )

Sets MARGIN_RIGHT and MARGIN_BOTTOM at the same time. This is a helper (see set_margin).

  • void set_focus_mode ( int mode )

Set the focus access mode for the control (FOCUS_NONE, FOCUS_CLICK, FOCUS_ALL). Only one Control can be focused at the same time, and it will receive keyboard signals.

  • void set_focus_neighbour ( int margin, NodePath neighbour )

Force a neighbour for moving the input focus to. When pressing TAB or directional/joypad directions focus is moved to the next control in that direction. However, the neighbour to move to can be forced with this function.

  • void set_global_position ( Vector2 pos )

Move the Control to a new position, relative to the top-left corner of the window Control, and without changing current anchor mode. (see set_margin).

  • void set_h_grow_direction ( int direction )
  • void set_h_size_flags ( int flags )

Hint for containers, set horizontal positioning flags.

  • void set_margin ( int margin, float offset )

Set a margin offset. Margin can be one of (MARGIN_LEFT, MARGIN_TOP, MARGIN_RIGHT, MARGIN_BOTTOM). Offset value being set depends on the anchor mode.

  • void set_mouse_filter ( int filter )

Set when the control is ignoring mouse events (even touchpad events send mouse events). (see the MOUSE_FILTER_* constants)

  • void set_pivot_offset ( Vector2 pivot_offset )
  • void set_position ( Vector2 pos )

Move the Control to a new position, relative to the top-left corner of the parent Control, changing all margins if needed and without changing current anchor mode. This is a helper (see set_margin).

  • void set_rotation ( float radians )

Set the rotation (in radians).

  • void set_rotation_deg ( float degrees )

Set the rotation (in degrees).

Changes MARGIN_RIGHT and MARGIN_BOTTOM to fit a given size. This is a helper (see set_margin).

  • void set_stretch_ratio ( float ratio )

Hint for containers, set the stretch ratio. This value is relative to other stretch ratio, so if this control has 2 and another has 1, this one will be twice as big.

  • void set_theme ( Theme theme )

Override whole the Theme for this Control and all its children controls.

  • void set_tooltip ( String tooltip )

Set a tooltip, which will appear when the cursor is resting over this control.

  • void set_v_grow_direction ( int direction )
  • void set_v_size_flags ( int flags )

Hint for containers, set vertical positioning flags.

  • void show_modal ( bool exclusive=false )

Display a Control as modal. Control must be a subwindow. Modal controls capture the input signals until closed or the area outside them is accessed. When a modal control loses focus, or the ESC key is pressed, they automatically hide. Modal controls are used extensively for popup dialogs and menus.

  • void warp_mouse ( Vector2 to_pos )