simvx.core.ui.ui_input

UIInputManager: UI input routing, focus, overlay scope, hit-testing.

All UI input flows through one contract: Control._on_gui_input(event). When a capturing overlay is open (registered via Control.show_overlay), routing is gated to that overlay’s chain (tree.overlays): a click outside the chain dismisses it, keyboard events go to the focused descendant with router-level fallbacks for Tab cycling and Escape-dismiss. A capture="none" overlay never scopes input, so the world keeps full input beneath it.

Module Contents

Classes

UIInputManager

Routes UI input events to controls: focus, hover, mouse grab, overlay scope.

Data

log

API

simvx.core.ui.ui_input.log

‘getLogger(…)’

class simvx.core.ui.ui_input.UIInputManager

Routes UI input events to controls: focus, hover, mouse grab, overlay scope.

Initialization

reset()

Reset transient state (called on scene change).

notify_subtree_removed(control)

Release focus / mouse grab when a control (or its subtree) leaves the tree.

Called from Control._exit_tree so that a destroyed or reparented focused control never lingers as the focus owner and keeps receiving keyboard events. The overlay registry’s own focus-restore path (OverlayLayer.close) handles overlay teardown separately.

ui_input(root: simvx.core.node.Node | None, mouse_pos=None, button: simvx.core.input.enums.MouseButton | None = None, pressed: bool = True, key: str = '', char: str = '')

Route a UI input event.

button is a MouseButton enum for mouse press/release events, or None for keyboard / char / pure mouse-move events.

touch_input(root: simvx.core.node.Node | None, finger_id: int, action: int, x: float, y: float)

Route a multi-touch event.

For controls with touch_mode='multi', each finger is tracked independently. On down: hit-test for the control, store in _touch_grabs, deliver press. On move: deliver to grabbed control. On up: deliver release, remove grab.

has_pending_edit() → bool

True if the focused control holds an uncommitted edit (e.g. a TextEdit).

commit_pending_edit() → None

Commit the focused control’s in-progress edit now, if it has one.

Idempotent (no-op when nothing is pending). Consumers call this before tearing down or replacing a focused editor so the typed value is not lost when the widget is removed (e.g. the inspector rebuilding after a rename).