.. _stdlib_ui_base: ====================== UIComponent, ui events ====================== ++++++++++++ Enumerations ++++++++++++ .. _enum-ui_base-UIFocusEventType: .. das:attribute:: UIFocusEventType The type of the focus event. :Values: * **FocusIn** = 0x0u8 - The element has received focus. * **FocusOut** = 0x1u8 - The element has lost focus. .. _enum-ui_base-UIInputEventPhase: .. das:attribute:: 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. .. _enum-ui_base-UIMouseEventType: .. das:attribute:: 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 ++++++++++ .. _struct-ui_base-UIInputEvent: .. das:attribute:: UIInputEvent The base structure for input events. :Fields: * **canvas** : :ref:`NodeId ` - The canvas node where the event occurred. * **phase** : :ref:`UIInputEventPhase ` - The phase of the input event. * **target** : :ref:`NodeId ` - The original node that triggered the event (e.g., the node where the mouse was clicked). * **currentTarget** : :ref:`NodeId ` - The node currently handling the event during propagation (changes as the event bubbles or captures through the hierarchy). .. _struct-ui_base-UIMouseEvent: .. das:attribute:: UIMouseEvent : UIInputEvent The structure for mouse events. :Fields: * **eventType** : :ref:`UIMouseEventType ` - The type of the mouse event. * **mouseButton** : :ref:`MouseButton ` - The mouse button that triggered the event. .. _struct-ui_base-UIFocusEvent: .. das:attribute:: UIFocusEvent : UIInputEvent The structure for UI focus events. Only nodes with UIComponent.interactable = true receive focus events. :Fields: * **eventType** : :ref:`UIFocusEventType ` - The type of the UI event. +++++++ Classes +++++++ .. _struct-ui_base-UIComponent: .. das:attribute:: 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). .. _function-ui_base_UIComponent_rq_invalidateInteractable_UIComponent_bool: .. das:function:: 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: .. _function-ui_base__dot__rq_interactable_UIComponent: .. das:operator:: UIComponent.interactable() : bool Returns the current interactable state. :Returns: * bool - True if the node is interactive and accepts input events. .. _function-ui_base__dot__rq_interactable_rq_clone_UIComponent_bool: .. das:operator:: UIComponent.interactable =(value: bool) Sets the interactable state. If the value changes, `invalidateInteractable()` is invoked to update related visual components. :Arguments: * **value** : bool .. _struct-ui_base-UIVisualState: .. das:attribute:: 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. .. _function-ui_base_UIVisualState_rq_setInteractable_UIVisualState_bool_bool: .. das:function:: UIVisualState.setInteractable(val: bool; doFade: bool) Sets whether the component is interactable. :Arguments: * **val** : bool * **doFade** : bool +++++++++ Functions +++++++++ * :ref:`UIInputEvent== (a: UIInputEvent; b: UIInputEvent) : bool ` * :ref:`UIInputEvent\!= (a: UIInputEvent; b: UIInputEvent) : bool ` * :ref:`UIMouseEvent== (a: UIMouseEvent; b: UIMouseEvent) : bool ` * :ref:`UIMouseEvent\!= (a: UIMouseEvent; b: UIMouseEvent) : bool ` * :ref:`UIFocusEvent== (a: UIFocusEvent; b: UIFocusEvent) : bool ` * :ref:`UIFocusEvent\!= (a: UIFocusEvent; b: UIFocusEvent) : bool ` * :ref:`add_ui_event_listener (node: NodeId; event_type: UIMouseEventType; listener: function\<(evt:UIMouseEvent):void\>) ` * :ref:`remove_ui_event_listener (node: NodeId; event_type: UIMouseEventType; listener: function\<(evt:UIMouseEvent):void\>) ` * :ref:`add_ui_event_listener (node: NodeId; event_type: UIFocusEventType; listener: function\<(evt:UIFocusEvent):void\>) ` * :ref:`remove_ui_event_listener (node: NodeId; event_type: UIFocusEventType; listener: function\<(evt:UIFocusEvent):void\>) ` * :ref:`add_ui_event_listener (event_type: UIMouseEventType; listener: function\<(evt:UIMouseEvent):void\>) ` * :ref:`remove_ui_event_listener (event_type: UIMouseEventType; listener: function\<(evt:UIMouseEvent):void\>) ` * :ref:`add_ui_event_listener (event_type: UIFocusEventType; listener: function\<(evt:UIFocusEvent):void\>) ` * :ref:`remove_ui_event_listener (event_type: UIFocusEventType; listener: function\<(evt:UIFocusEvent):void\>) ` * :ref:`get_ui_mouse_position (node: NodeId; var res: float3&) : bool ` * :ref:`get_ui_mouse_position (node: NodeId) : float3 ` * :ref:`is_mouse_inside_frame (frame: UIFrame?) : bool ` * :ref:`set_ui_focus_node (comp: UIComponent const?) : bool ` * :ref:`get_ui_focused_node () : NodeId ` * :ref:`stop_immediate_propagation (event: UIMouseEvent|UIFocusEvent) : auto ` * :ref:`stop_propagation (event: UIMouseEvent|UIFocusEvent) : auto ` .. _function-ui_base__eq__eq__UIInputEvent_UIInputEvent: .. das:function:: UIInputEvent==(a: UIInputEvent; b: UIInputEvent) : bool Compares two UIInputEvent structures. :Arguments: * **a** : :ref:`UIInputEvent ` * **b** : :ref:`UIInputEvent ` :Returns: * bool - True if the structures are equal, false otherwise. .. _function-ui_base__ex__eq__UIInputEvent_UIInputEvent: .. das:function:: UIInputEvent!=(a: UIInputEvent; b: UIInputEvent) : bool Compares two UIInputEvent structures. :Arguments: * **a** : :ref:`UIInputEvent ` * **b** : :ref:`UIInputEvent ` :Returns: * bool - True if the structures are not equal, false otherwise. .. _function-ui_base__eq__eq__UIMouseEvent_UIMouseEvent: .. das:function:: UIMouseEvent==(a: UIMouseEvent; b: UIMouseEvent) : bool Compares two UIMouseEvent structures. :Arguments: * **a** : :ref:`UIMouseEvent ` * **b** : :ref:`UIMouseEvent ` :Returns: * bool - True if the structures are equal, false otherwise. .. _function-ui_base__ex__eq__UIMouseEvent_UIMouseEvent: .. das:function:: UIMouseEvent!=(a: UIMouseEvent; b: UIMouseEvent) : bool Compares two UIMouseEvent structures. :Arguments: * **a** : :ref:`UIMouseEvent ` * **b** : :ref:`UIMouseEvent ` :Returns: * bool - True if the structures are not equal, false otherwise. .. _function-ui_base__eq__eq__UIFocusEvent_UIFocusEvent: .. das:function:: UIFocusEvent==(a: UIFocusEvent; b: UIFocusEvent) : bool Compares two UIFocusEvent structures. :Arguments: * **a** : :ref:`UIFocusEvent ` * **b** : :ref:`UIFocusEvent ` :Returns: * bool - True if the structures are equal, false otherwise. .. _function-ui_base__ex__eq__UIFocusEvent_UIFocusEvent: .. das:function:: UIFocusEvent!=(a: UIFocusEvent; b: UIFocusEvent) : bool Compares two UIFocusEvent structures. :Arguments: * **a** : :ref:`UIFocusEvent ` * **b** : :ref:`UIFocusEvent ` :Returns: * bool - True if the structures are not equal, false otherwise. .. _function-ui_base_add_ui_event_listener_NodeId_UIMouseEventType_function_ls_evt_c_UIMouseEvent_c_void_gr_: .. das:function:: 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: * **node** : :ref:`NodeId ` * **event_type** : :ref:`UIMouseEventType ` * **listener** : function<(evt: :ref:`UIMouseEvent ` ):void> .. _function-ui_base_remove_ui_event_listener_NodeId_UIMouseEventType_function_ls_evt_c_UIMouseEvent_c_void_gr_: .. das:function:: 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: * **node** : :ref:`NodeId ` * **event_type** : :ref:`UIMouseEventType ` * **listener** : function<(evt: :ref:`UIMouseEvent ` ):void> .. _function-ui_base_add_ui_event_listener_NodeId_UIFocusEventType_function_ls_evt_c_UIFocusEvent_c_void_gr_: .. das:function:: 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: * **node** : :ref:`NodeId ` * **event_type** : :ref:`UIFocusEventType ` * **listener** : function<(evt: :ref:`UIFocusEvent ` ):void> .. _function-ui_base_remove_ui_event_listener_NodeId_UIFocusEventType_function_ls_evt_c_UIFocusEvent_c_void_gr_: .. das:function:: 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: * **node** : :ref:`NodeId ` * **event_type** : :ref:`UIFocusEventType ` * **listener** : function<(evt: :ref:`UIFocusEvent ` ):void> .. _function-ui_base_add_ui_event_listener_UIMouseEventType_function_ls_evt_c_UIMouseEvent_c_void_gr_: .. das:function:: 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: * **event_type** : :ref:`UIMouseEventType ` * **listener** : function<(evt: :ref:`UIMouseEvent ` ):void> .. _function-ui_base_remove_ui_event_listener_UIMouseEventType_function_ls_evt_c_UIMouseEvent_c_void_gr_: .. das:function:: 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: * **event_type** : :ref:`UIMouseEventType ` * **listener** : function<(evt: :ref:`UIMouseEvent ` ):void> .. _function-ui_base_add_ui_event_listener_UIFocusEventType_function_ls_evt_c_UIFocusEvent_c_void_gr_: .. das:function:: 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: * **event_type** : :ref:`UIFocusEventType ` * **listener** : function<(evt: :ref:`UIFocusEvent ` ):void> .. _function-ui_base_remove_ui_event_listener_UIFocusEventType_function_ls_evt_c_UIFocusEvent_c_void_gr_: .. das:function:: 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: * **event_type** : :ref:`UIFocusEventType ` * **listener** : function<(evt: :ref:`UIFocusEvent ` ):void> .. _function-ui_base_get_ui_mouse_position_NodeId_float3: .. das:function:: get_ui_mouse_position(node: NodeId; res: float3&) : bool Gets the mouse position in the local space of the node. :Arguments: * **node** : :ref:`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. .. _function-ui_base_get_ui_mouse_position_NodeId: .. das:function:: get_ui_mouse_position(node: NodeId) : float3 Gets the mouse position in the local space of the node. :Arguments: * **node** : :ref:`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. .. _function-ui_base_is_mouse_inside_frame_UIFrame_q_: .. das:function:: is_mouse_inside_frame(frame: UIFrame?) : bool Checks if the mouse is inside the given UI frame. :Arguments: * **frame** : :ref:`UIFrame ` ? - The UI frame to check. :Returns: * bool - True if the mouse is inside the frame, false otherwise. .. _function-ui_base_set_ui_focus_node_UIComponent_const_q_: .. das:function:: 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: * **comp** : :ref:`UIComponent ` ? - The UI component to focus. :Returns: * bool - True if the focus was successfully set, false otherwise. .. note:: Only nodes with `UIComponent.interactable` = true can receive focus. .. _function-ui_base_get_ui_focused_node: .. das:function:: get_ui_focused_node() : NodeId Returns the currently focused UI node. .. _function-ui_base_stop_immediate_propagation_UIMouseEventUIFocusEvent: .. das:function:: stop_immediate_propagation(event: UIMouseEvent|UIFocusEvent) : auto Stops the propagation of the event. Propagation stops immediately after the current event handler is finished. :Arguments: * **event** : option< :ref:`UIMouseEvent ` | :ref:`UIFocusEvent ` > - The event to stop the propagation for. 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) .. _function-ui_base_stop_propagation_UIMouseEventUIFocusEvent: .. das:function:: 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: * **event** : option< :ref:`UIMouseEvent ` | :ref:`UIFocusEvent ` > - The event to stop the propagation for. 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)