Source code for simvx.core.input.enums

"""Controller and pointer enumerations for the input system.

Keys, pointer and tablet buttons are not here: they are controls of a device
type, which is :mod:`simvx.core.input.controls`.
"""

from enum import IntEnum, StrEnum




class InputMethod(StrEnum):
    """What the player is using right now, for prompts and for on-screen controls.

    Not what the machine has: ``Input.capabilities`` answers that. This is the
    one the player last acted with, so a game shows "Press A" while they hold a
    controller and "Press Space" the moment they touch the keyboard.
    """

    KEYBOARD_MOUSE = "keyboard_mouse"
    CONTROLLER = "controller"
    TOUCH = "touch"





class ControllerSource(StrEnum):
    """Where a pad in ``Input.controllers`` came from.

    A lobby that wants only real controllers filters on this; everything else
    treats the three alike, which is the point of the on-screen pad being a pad.
    """

    #: A controller the machine has, reported by a window backend or the browser.
    DEVICE = "device"
    #: A pad a test published through ``InputSimulator``.
    SIMULATED = "simulated"
    #: The on-screen pad a touch player is using.
    VIRTUAL = "virtual"





class ControllerFamily(StrEnum):
    """Which controller family a pad belongs to, which decides what a prompt draws.

    A pad's controls are positional on every family, so ``Controller.A`` is the
    bottom face button whichever pad is plugged in; only the label printed on
    it moves.
    """

    XBOX = "xbox"
    PLAYSTATION = "playstation"
    NINTENDO = "nintendo"
    #: A pad with the standard layout that names no family the engine knows.
    GENERIC = "generic"
    #: A device with no standard controller layout: a flight stick, a wheel, an
    #: arcade stick. Its buttons and axes are the driver's indices.
    JOYSTICK = "joystick"





class MouseCaptureMode(IntEnum):
    """Mouse cursor capture modes."""

    VISIBLE = 0
    HIDDEN = 1
    CAPTURED = 2
    CONFINED = 3





class CursorShape(StrEnum):
    """The shape of the operating system's pointer over a control.

    Each maps to the platform's own cursor of that name, and to the CSS cursor
    of the same meaning in the browser. A backend without one shows ``ARROW``.
    """

    ARROW = "arrow"
    IBEAM = "ibeam"
    CROSSHAIR = "crosshair"
    POINTING_HAND = "pointing_hand"
    RESIZE_EW = "resize_ew"
    RESIZE_NS = "resize_ns"
    RESIZE_NWSE = "resize_nwse"
    RESIZE_NESW = "resize_nesw"
    MOVE = "move"
    NOT_ALLOWED = "not_allowed"





class PointerType(StrEnum):
    """What kind of pointer produced an event. A finger and a pen are pointers too."""

    MOUSE = "mouse"
    TOUCH = "touch"
    PEN = "pen"





class PointerPhase(StrEnum):
    """What a pointer did. The one spelling for a pointer edge."""

    DOWN = "down"
    MOVE = "move"
    UP = "up"
    #: The system took the pointer away mid-gesture. It fires no release edge.
    CANCEL = "cancel"
    #: A pen came into the digitiser's range.
    ENTER = "enter"
    #: A pen left the digitiser's range.
    LEAVE = "leave"





class PointerTool(StrEnum):
    """Which working end of a pointer is making the contact.

    A mouse and a finger report ``TIP``: the contact they make is their only
    one. A pen reports the end it is using, which is how an eraser is told from
    the tip on every platform, whether the platform calls it a tool, a flag or
    a second device. A change of tool closes the current contact and opens a
    new one, so a handler never sees the tool change inside a stroke.
    """

    TIP = "tip"
    ERASER = "eraser"
    #: A tip with a finger wheel, reported through ``tangential_pressure``.
    AIRBRUSH = "airbrush"
    #: An absolute puck or lens, not a drawing tip.
    PUCK = "puck"





class PenAxis(StrEnum):
    """A pen measurement the hardware can report, for ``Input.capabilities.pen_axes``.

    Each is an axis whose absent value collides with a real one, so whether it
    was measured is a capability rather than a magic number: a brush panel
    greys out the sliders the artist's pen cannot drive.
    """

    PRESSURE = "pressure"
    TILT = "tilt"
    TWIST = "twist"
    DISTANCE = "distance"
    TANGENTIAL = "tangential"





class FocusMode(StrEnum):
    """How a node takes keyboard focus. Each mode includes the ones before it.

    Members:
        NONE: Never holds focus.
        CLICK: Takes focus when pressed, and from code; not a Tab stop.
        ALL: Also a Tab stop and a directional-focus destination.
        HOVER: Also takes focus when the mouse or pen comes to rest over it,
            under the rules :class:`~simvx.core.ui.ui_input.UIInputManager`
            applies to hover focus. A finger never moves focus by hovering.

    A property takes the member or its plain string: ``focus_mode = "all"``.
    """

    NONE = "none"
    CLICK = "click"
    ALL = "all"
    HOVER = "hover"



    @property
    def takes_focus(self) -> bool:
        """Whether a node in this mode can hold focus at all."""
        return self is not FocusMode.NONE




    @property
    def in_tab_order(self) -> bool:
        """Whether Tab and directional focus reach a node in this mode."""
        return self is FocusMode.ALL or self is FocusMode.HOVER




    @property
    def follows_hover(self) -> bool:
        """Whether the pointer resting over a node in this mode focuses it."""
        return self is FocusMode.HOVER






class FocusReason(StrEnum):
    """Why keyboard focus last moved, which ``tree.focus_reason`` records with every change.

    A widget that draws a focus ring only for the keyboard, or a tutorial that
    reacts to the player reaching a button, reads it rather than guessing.
    """

    CODE = "code"  # grab_focus / release_focus, or a widget moving it itself
    CLICK = "click"  # a press on the node, or on nothing, which clears it
    TAB = "tab"  # Tab or Shift+Tab traversal
    DIRECTION = "direction"  # a D-pad, stick or arrow move
    HOVER = "hover"  # the mouse or pen came to rest over a HOVER node
    OVERLAY = "overlay"  # an overlay opening elected its initial focus, or closing restored it
    LEFT = "left"  # the owner left the tree, hid or was disabled