Custom GUI controls

    For drawing, it is recommended to check the tutorial. The same applies. Some functions are worth mentioning due to their usefulness when drawing, so they will be detailed next:

    Unlike 2D nodes, “size” is important with controls, as it helps to organize them in proper layouts. For this, the Control.rect_size property is provided. Checking it during is vital to ensure everything is kept in-bounds.

    Some controls (such as buttons or text editors) might provide input focus for keyboard or joypad input. Examples of this are entering text or pressing a button. This is controlled with the property. When drawing, and if the control supports input focus, it is always desired to show some sort of indicator (highlight, box, etc.) to indicate that this is the currently focused control. To check for this status, the Control.has_focus() method exists. Example

    GDScript

    C#

    1. public override void _Draw()
    2. {
    3.     if (HasFocus())
    4.     {
    5.         DrawSelected()
    6.     }
    7.     else
    8.     {
    9.         DrawNormal();
    10.     }
    11. }

    As mentioned before, size is important to controls. This allows them to lay out properly, when set into grids, containers, or anchored. Controls, most of the time, provide a minimum size to help properly lay them out. For example, if controls are placed vertically on top of each other using a , the minimum size will make sure your custom control is not squished by the other controls in the container.

    GDScript

    C#

    1.     return Vector2(30, 30)

    Alternatively, set it using a function:

    GDScript

    C#

    1. func _ready():
    2.     set_custom_minimum_size(Vector2(30, 30))
    2. {
    3.     SetCustomMinimumSize(new Vector2(20, 20));
    4. }

    Controls provide a few helpers to make managing input events much easier than regular nodes.

    • The mouse pointer is over the control.
    • The button was pressed over this control (control always captures input until button is released)
    • Control provides keyboard/joypad focus via Control.focus_mode.

    This function is . Simply override it in your control. No processing needs to be set.

    GDScript

    C#

    1. public override void _GuiInput(InputEvent @event)
    2. {
    3.     if (@event is InputEventMouseButton mbe && mbe.ButtonIndex == (int)ButtonList.Left && mbe.Pressed)
    4.     {
    5.         GD.Print("Left mouse button was pressed!");
    6.     }
    7. }

    For more information about events themselves, check the InputEvent tutorial.

    Controls also have many useful notifications for which no dedicated callback exists, but which can be checked with the _notification callback:

    GDScript

    1. func _notification(what):
    2.     match what:
    3.             pass # Mouse entered the area of this control.
    4.         NOTIFICATION_MOUSE_EXIT:
    6.         NOTIFICATION_FOCUS_ENTER:
    7.             pass # Control gained focus.
    8.         NOTIFICATION_FOCUS_EXIT:
    9.             pass # Control lost focus.
    10.         NOTIFICATION_THEME_CHANGED:
    11.             pass # Theme used to draw the control changed;
    12.             # update and redraw is recommended if using a theme.
    13.         NOTIFICATION_VISIBILITY_CHANGED:
    14.             pass # Control became visible/invisible;
    15.             # check new status with is_visible().
    16.         NOTIFICATION_RESIZED:
    17.             pass # Control changed size; check new size
    18.             # with get_size().
    19.         NOTIFICATION_MODAL_CLOSE:
    20.             pass # For modal pop-ups, notification