UIComponent, ui events

Enumerations

UIFocusEventType

The type of the focus event.

Values:

  • FocusIn = 0x0u8 - The element has received focus.

  • FocusOut = 0x1u8 - The element has lost focus.

UIInputEventPhase

The phase of the input event.

Values:

  • Capture = 0 - The event is captured by ancestors before the target.

  • Target = 1 - The event is at the target node.

  • Bubble = 2 - The event is bubbling up the hierarchy after the target.

UIMouseEventType

The type of the mouse event.

Values:

  • MouseDown = 0x0u8 - The mouse button is pressed.

  • MouseUp = 0x1u8 - The mouse button is released.

  • MouseMove = 0x2u8 - The mouse cursor is over the target and is moving.

  • MouseOver = 0x3u8 - The mouse cursor enters the target.

  • MouseOut = 0x4u8 - The mouse cursor leaves the target.

  • MouseClick = 0x5u8 - Click event (mouse button is pressed and released on the same target).

Structures

UIInputEvent

The base structure for input events.

Fields:

  • canvas : NodeId - The canvas node where the event occurred.

  • phase : UIInputEventPhase - The phase of the input event.

  • target : NodeId - The original node that triggered the event (e.g., the node where the mouse was clicked).

  • currentTarget : NodeId - The node currently handling the event during propagation (changes as the event bubbles or captures through the hierarchy).

UIMouseEvent : UIInputEvent

The structure for mouse events.

Fields:
UIFocusEvent : UIInputEvent

The structure for UI focus events. Only nodes with UIComponent.interactable = true receive focus events.

Fields:

Classes

UIComponent : Component

Note

UIFrame component is automatically added to the node if it is not already present

Base class for all UI components. Component that marks a node as “interactive” in the UI system. Controls whether the node receives input events (mouse, focus).

UIComponent.invalidateInteractable(doFade: bool)

Applies the current interactable flag to all UIVisualState instances attached to the node. Used to allow visual components to switch between disabled/enabled visual states.

Arguments:

  • doFade : bool

Properties:

UIComponent.interactable: bool

Returns the current interactable state. :Returns: * bool - True if the node is interactive and accepts input events.

UIComponent.interactable =(value: bool)

Sets the interactable state. If the value changes, invalidateInteractable() is invoked to update related visual components.

Arguments:

  • value : bool

UIVisualState : Component

Note

UIFrame component is automatically added to the node if it is not already present

A component that manages the visual state of a UI element.

UIVisualState.setInteractable(val: bool; doFade: bool)

Sets whether the component is interactable.

Arguments:

  • val : bool

  • doFade : bool

Functions

UIInputEvent==(a: UIInputEvent; b: UIInputEvent): bool

Compares two UIInputEvent structures. :Arguments: * a : UIInputEvent

Returns:

  • bool - True if the structures are equal, false otherwise.

UIInputEvent!=(a: UIInputEvent; b: UIInputEvent): bool

Compares two UIInputEvent structures. :Arguments: * a : UIInputEvent

Returns:

  • bool - True if the structures are not equal, false otherwise.

UIMouseEvent==(a: UIMouseEvent; b: UIMouseEvent): bool

Compares two UIMouseEvent structures. :Arguments: * a : UIMouseEvent

Returns:

  • bool - True if the structures are equal, false otherwise.

UIMouseEvent!=(a: UIMouseEvent; b: UIMouseEvent): bool

Compares two UIMouseEvent structures. :Arguments: * a : UIMouseEvent

Returns:

  • bool - True if the structures are not equal, false otherwise.

UIFocusEvent==(a: UIFocusEvent; b: UIFocusEvent): bool

Compares two UIFocusEvent structures. :Arguments: * a : UIFocusEvent

Returns:

  • bool - True if the structures are equal, false otherwise.

UIFocusEvent!=(a: UIFocusEvent; b: UIFocusEvent): bool

Compares two UIFocusEvent structures. :Arguments: * a : UIFocusEvent

Returns:

  • bool - True if the structures are not equal, false otherwise.

add_ui_event_listener(node: NodeId; event_type: UIMouseEventType; listener: function<(evt:UIMouseEvent):void>)

Adds a listener for a UI mouse event for a specific node.

Usage example:

def button_mouse_event_handler(evt : UIMouseEvent) {
    if (evt.phase == UIInputEventPhase.Target) {
        print("Button {evt.currentTarget} is clicked!")
    }
}
...
add_ui_event_listener(btn, UIMouseEventType.MouseClick, @@button_mouse_click_event_handler)
Arguments:
remove_ui_event_listener(node: NodeId; event_type: UIMouseEventType; listener: function<(evt:UIMouseEvent):void>)

Removes a listener for a UI mouse events for a specific node.

Usage example:

remove_ui_event_listener(btn, UIMouseEventType.MouseClick, @@button_mouse_click_event_handler)
Arguments:
add_ui_event_listener(node: NodeId; event_type: UIFocusEventType; listener: function<(evt:UIFocusEvent):void>)

Adds a listener for a UI focus event for a specific node.

Usage example:

def button_focus_event_handler(evt : UIFocusEvent) {
    if (evt.phase == UIInputEventPhase.Target) {
        print("Button {evt.currentTarget} is focused!")
    }
}
...
add_ui_event_listener(btn, UIFocusEventType.FocusIn, @@button_focus_event_handler)

Note

Only nodes with UIComponent.interactable = true receive focus events. Focus events are only sent in the Target phase (no Capture or Bubble).

Arguments:
remove_ui_event_listener(node: NodeId; event_type: UIFocusEventType; listener: function<(evt:UIFocusEvent):void>)

Removes a listener for a UI focus event for a specific node.

Usage example:

remove_ui_event_listener(btn, UIFocusEventType.FocusIn, @@button_focus_event_handler)
Arguments:
add_ui_event_listener(event_type: UIMouseEventType; listener: function<(evt:UIMouseEvent):void>)

Adds a global listener for UI mouse events.

Usage example:

def mouse_event_handler(evt : UIMouseEvent) {
    if (evt.phase == UIInputEventPhase.Target) {
        print("{evt.currentTarget} is clicked!")
    }
}
...
add_ui_event_listener(UIMouseEventType.MouseClick, @@mouse_event_handler)

Note

Only nodes with UIComponent.interactable = true receive focus events. Focus events are only sent in the Target phase (no Capture or Bubble).

Arguments:
remove_ui_event_listener(event_type: UIMouseEventType; listener: function<(evt:UIMouseEvent):void>)

Removes a global listener for UI mouse events.

Usage example:

remove_ui_event_listener(UIMouseEventType.MouseClick, @@mouse_event_handler)
Arguments:
add_ui_event_listener(event_type: UIFocusEventType; listener: function<(evt:UIFocusEvent):void>)

Adds a global listener for UI focus events.

Usage example:

def focus_event_handler(evt : UIFocusEvent) {
    if (evt.phase == UIInputEventPhase.Target) {
        print("{evt.currentTarget} is focused!")
    }
}
...
add_ui_event_listener(btn, UIFocusEventType.FocusIn, @@focus_event_handler)
Arguments:
remove_ui_event_listener(event_type: UIFocusEventType; listener: function<(evt:UIFocusEvent):void>)

Removes a global listener for UI focus events.

Usage example:

remove_ui_event_listener(btn, UIFocusEventType.FocusIn, @@focus_event_handler)
Arguments:
get_ui_mouse_position(node: NodeId; res: float3&): bool

Gets the mouse position in the local space of the node.

Arguments:

  • node : NodeId - The node to get the mouse position for.

  • res : float3& - The resulting mouse position in the local space of the node.

Returns:

  • bool - True if position is calculated, false otherwise.

get_ui_mouse_position(node: NodeId): float3

Gets the mouse position in the local space of the node.

Arguments:

  • node : NodeId - The node to get the mouse position for.

Returns:

  • float3 - The mouse position in the local space of the node. Zero if position cannot be calculated.

is_mouse_inside_frame(frame: UIFrame?): bool

Checks if the mouse is inside the given UI frame.

Arguments:

  • frame : UIFrame ? - The UI frame to check.

Returns:

  • bool - True if the mouse is inside the frame, false otherwise.

set_ui_focus_node(comp: UIComponent const?): bool

Sets the UI input/focus to the specified UIComponent. This function attempts to make the given UI component the current focus target. If another component was previously focused, it will lose focus. set_ui_focus_node(null) can be used to clear the current focus.

Arguments:
Returns:

  • bool - True if the focus was successfully set, false otherwise.

Note

Only nodes with UIComponent.interactable = true can receive focus.

get_ui_focused_node(): NodeId

Returns the currently focused UI node.

stop_immediate_propagation(event: UIMouseEvent|UIFocusEvent): auto

Stops the propagation of the event. Propagation stops immediately after the current event handler is finished.

Arguments:

Usage example:

def button_mouse_click_event_handler(evt : UIMouseEvent) {
    if (evt.phase == UIInputEventPhase.Target) {
        print("Button {evt.target} is clicked!")
        stop_immediate_propagation(evt)
    }
}
...
add_ui_event_listener(btn, UIMouseEventType.MouseClick, @@button_mouse_click_event_handler)
stop_propagation(event: UIMouseEvent|UIFocusEvent): auto

Stops the propagation of the event. This function doesn’t affect currentTarget’s listeners, all of them will be called.

Arguments:

Usage example:

def button_mouse_click_event_handler(evt : UIMouseEvent) {
    if (evt.phase == UIInputEventPhase.Target) {
        print("Mouse is down on node {evt.target}")
        stop_propagation(evt)
    }
}
...
add_ui_event_listener(btn, UIMouseEventType.MouseClick, @@button_mouse_click_event_handler)