simvx.core.ui.navigation

Which input drives UI navigation: the eight ui_* actions.

The router never tests a key name or a button code of its own. It asks this module whether what arrived is ui_focus_next, ui_focus_prev, ui_accept, ui_cancel or one of the four directions. Those are engine entries (:mod:simvx.core.input.engine), actions every tree’s map has at its bottom, so navigation is bound the way every other action is and an author can move it:

.. code-block:: python

input_context = {"ui_focus_next": [Key.CTRL + Key.TAB]}   # Tab is now free
input_context = {"ui_focus_next": []}                     # no bindings: unbound

A player moves one with InputMap.rebind("ui_accept", Key.SPACE).

A key is matched by the rule every binding is read by (:meth:~simvx.core.input.events.InputBinding.matches_key): the engine’s Tab is exact, so Tab and Shift+Tab are two different answers.

ui_accept activates the focus owner: the router calls

meth:

~simvx.core.ui.core.Control.activate on it, which presses a Button, toggles a CheckBox, selects a RadioButton and does nothing anywhere else. Rebinding the action moves activation with it, and a widget that wants the key for itself claims it first, so a focused text field keeps Enter for submit.

Module Contents

Functions

ui_action_bindings	Every binding on a navigation action in input_map, or in the tree in play’s when it is None.
ui_action_keys	Key combos currently bound to action, defaults included.
ui_action_matches	True when the key event is bound to action.
ui_actions_for_pad_event	Which navigation actions a pad event opens or closes, as (action, pressed).

Data

UI_DIRECTIONS
__all__

API

simvx.core.ui.navigation.UI_DIRECTIONS: dict[str, simvx.core.ui.enums.FocusDirection]

None

simvx.core.ui.navigation.__all__

[‘UI_ACCEPT’, ‘UI_CANCEL’, ‘UI_DIRECTIONS’, ‘UI_DOWN’, ‘UI_FOCUS_NEXT’, ‘UI_FOCUS_PREV’, ‘UI_LEFT’, …

simvx.core.ui.navigation.ui_action_bindings(action: str, input_map: Any = None) → tuple[simvx.core.input.events.InputBinding, ...]

Every binding on a navigation action in input_map, or in the tree in play’s when it is None.

With no tree at all the engine’s own bindings answer. Declaring the action with no bindings disables it on every device at once.

simvx.core.ui.navigation.ui_action_keys(action: str, input_map: Any = None) → tuple[str, ...]

Key combos currently bound to action, defaults included.

simvx.core.ui.navigation.ui_action_matches(action: str, event: simvx.core.input.events.KeyEvent, input_map: Any = None) → bool

True when the key event is bound to action.

The match is field by field against each binding’s key and modifier flags (:meth:~simvx.core.input.events.InputBinding.matches_key) and it is exact, so Tab and Shift+Tab are two different answers.

Handed anything but a :class:~simvx.core.input.events.KeyEvent this raises rather than answering False. Every route into UI navigation used to pass a combo string, and a string arriving here would silently match nothing: a dialog that stopped closing on Escape and a Tab that stopped moving focus, with no error anywhere.

simvx.core.ui.navigation.ui_actions_for_pad_event(event: simvx.core.input.events.ButtonEvent | simvx.core.input.events.AxisEvent, input_state: Any, input_map: Any = None) → list[tuple[str, bool]]

Which navigation actions a pad event opens or closes, as (action, pressed).

A button carries its own edge. A stick does not: it becomes an edge only where it crosses a binding’s deadzone in the direction that binding names, measured against the value the axis held before this frame, which is the same test the polling path uses. So one stick event can close ui_left and open ui_right in a single flick, and a stick pushed and held reports one press rather than one per poll.

input_state is the _Input the event belongs to; it owns both the threshold test and the frame-start value, so a handler and a poll cannot drift apart.