Skip to content

class_control

Jump to bottom Edit New page
reduz edited this page Feb 23, 2014 · 11 revisions

Control

Inherits: CanvasItem\n\n

Brief Description

Control is the base node for all the GUI components.

Member Functions

Signals

  • ** focus_enter ** ( )
  • ** mouse_enter ** ( )
  • ** resized ** ( )
  • ** minimum_size_changed ** ( )
  • ** size_flags_changed ** ( )
  • ** focus_exit ** ( )
  • ** input_event ** ( )
  • ** mouse_exit ** ( )

Numeric Constants

  • 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,
  • ANCHOR_RATIO = 2 - X and Y are a ratio (0 to 1) relative to the parent size 0 is left/top, 1 is right/bottom.
  • 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
  • SIZE_EXPAND = 1
  • SIZE_FILL = 2
  • SIZE_EXPAND_FILL = 3

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 (inputevent) 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 [Node._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|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 overrided per each control by calling the add*_override functions, or from the editor.

Member Function Description

_input_event

get_minimum_size

  • 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.

accept_event

get_minimum_size

  • 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.

is_window

  • bool ** is_window ** ( ) const \ Return wether this control is a //window//. Controls are considered windows when their parent node is not a Control.

get_window

set_anchor

  • void ** set_anchor ** ( int margin, int anchor_mode ) \ Change the anchor (ANCHOR_BEGIN, ANCHOR_END, ANCHOR_RATIO) type for a margin (MARGIN_LEFT, MARGIN_TOP, MARGIN_RIGHT, MARGIN_BOTTOM). Changing the anchor mode converts the current margin offset from the previos anchor mode to the new one, so margin offsets (#set_margin) must be done after setting anchors, or at the same time (#set_anchor_and_margin).

get_anchor

  • int ** get_anchor ** ( int margin ) const \ Return the anchor type (ANCHOR_BEGIN, ANCHOR_END, ANCHOR_RATIO) for a given margin (MARGIN_LEFT, MARGIN_TOP, MARGIN_RIGHT, MARGIN_BOTTOM).

set_margin

  • void ** set_margin ** ( int margin, real 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.

set_anchor_and_margin

  • void ** set_anchor_and_margin ** ( int margin, int anchor_mode, real offset ) \ Change the anchor (ANCHOR_BEGIN, ANCHOR_END, ANCHOR_RATIO) type for a margin (MARGIN_LEFT, MARGIN_TOP, MARGIN_RIGHT, MARGIN_BOTTOM), and also set its offset. This is a helper (see #set_anchor and #set_margin).

set_begin

set_end

  • void ** set_end ** ( Vector2 pos ) \ Sets MARGIN_RIGHT and MARGIN_BOTTOM at the same time. This is a helper (see #set_margin).

set_pos

  • void ** set_pos ** ( 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).

set_size

  • void ** set_size ** ( Vector2 size ) \ Changes MARGIN_RIGHT and MARGIN_BOTTOM to fit a given size. This is a helper (see #set_margin).

set_global_pos

  • void ** set_global_pos ** ( 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).

get_margin

  • real ** get_margin ** ( int margin ) const \ 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.

get_end

get_pos

  • Vector2 ** get_pos ** ( ) const \ Returns the Control position, relative to the top-left corner of the parent Control and independly of the anchor mode.

get_size

  • Vector2 ** get_size ** ( ) const \ 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).

get_global_pos

  • Vector2 ** get_global_pos ** ( ) const \ Returns the Control position, relative to the top-left corner of the parent Control and independent of the anchor mode.

get_rect

  • 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_pos,#get_size).

get_global_rect

set_area_as_parent_rect

show_modal

  • void ** show_modal ** ( bool exclusive=false ) \ Display a Control as modal. Control must be a subwindow (see #set_as_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.

set_focus_mode

  • 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.

has_focus

grab_focus

release_focus

  • void ** release_focus ** ( ) \ Give up the focus, no other control will be able to receive keyboard input.

get_focus_owner

  • Control ** get_focus_owner ** ( ) const \ Return which control is owning the keyboard focus, or null if no one.

set_h_size_flags

  • void ** set_h_size_flags ** ( int flags ) \ Hint for containers, set horizontal positioning flags.

get_h_size_flags

  • int ** get_h_size_flags ** ( ) const \ Hint for containers, return horizontal positioning flags.

set_stretch_ratio

  • void ** set_stretch_ratio ** ( real 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.

get_stretch_ratio

  • real ** 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.

set_v_size_flags

  • void ** set_v_size_flags ** ( int flags ) \ Hint for containers, set vertical positioning flags.

get_v_size_flags

  • int ** get_v_size_flags ** ( ) const \ Hint for containers, return vertical positioning flags.

set_theme

  • void ** set_theme ** ( Theme theme ) \ Override whole the theme for this Control and all its children controls.

get_theme

add_icon_override

add_style_override

  • void ** add_style_override ** ( String name, StyleBox stylebox ) \ Override a single stylebox ([Stylebox]) in the theme of this Control. If stylebox is empty, override is cleared.

add_font_override

  • 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.

add_constant_override

  • 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.

set_tooltip

  • void ** set_tooltip ** ( String tooltip ) \ Set a tooltip, which will appear when the cursor is resting over this control.

get_tooltip

  • String ** get_tooltip ** ( Vector2 atpos=Vector2(0,0) ) const \ Return the tooltip, which will appear when the cursor is resting over this control.

set_default_cursor_shape

  • void ** set_default_cursor_shape ** ( int shape ) \ Set the default cursor shape for this control. See enum CURSOR_* for the list of shapes.

get_default_cursor_shape

  • int ** get_default_cursor_shape ** ( ) const \ Return the default cursor shape for this control. See enum CURSOR_* for the list of shapes.

get_cursor_shape

set_focus_neighbour

  • 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.

get_focus_neighbour

  • NodePath ** get_focus_neighbour ** ( int margin ) const \ 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.

set_ignore_mouse

  • void ** set_ignore_mouse ** ( bool ignore ) \ Ignore mouse events on this control (even touchpad events send mouse events).

is_ignoring_mouse

  • bool ** is_ignoring_mouse ** ( ) const \ Return if the control is ignoring mouse events (even touchpad events send mouse events).
Add a custom footer
Add a custom sidebar

Clone this wiki locally