<!-- Source: https://medius.k4tech.net/library/types/enums -->
# Enums

_Command and status enumerations_

Command and status enums, each tied to a wire byte. Conversion helpers are listed with each.

## DeviceKind

_The cloned device's primary kind_

```text
enum DeviceKind { Unknown, Keyboard, Mouse }
```

The `kind` field of a [`DeviceInfo`](/library/types/structs.md#device-info), read from the cloned device's USB Boot-interface `bInterfaceProtocol`. It also drives [`find_mouse_box`](/library/discovery.md#find-mouse-box) and [`find_keyboard_box`](/library/discovery.md#find-keyboard-box). `Display` prints the lowercase name.

| Variant | Byte | Meaning |
| --- | --- | --- |
| `Unknown` | `0` | Neither a Boot keyboard nor a Boot mouse. |
| `Keyboard` | `1` | The device is a keyboard. |
| `Mouse` | `2` | The device is a mouse. |

## Button

_The button a command acts on_

```text
enum Button { Left, Right, Middle, Side1, Side2 }
```

The button an [`INJECT`](/native/commands/inject.md#inject) command acts on. A `Button` converts `Into<[Usage](/library/types/enums.md#usage)>` as class button, so you pass one straight to [`inject`](/library/inject.md#inject). Convert with `as_id() -> u8` and `from_id(u8) -> Option<Button>`.

| Variant | id | Meaning |
| --- | --- | --- |
| `Left` | `0` | Left button. |
| `Right` | `1` | Right button. |
| `Middle` | `2` | Middle button. |
| `Side1` | `3` | First thumb button. |
| `Side2` | `4` | Second thumb button. |

## Action

_The shared press / release tri-state_

```text
enum Action { SoftRelease, Press, ForceRelease }
```

The shared override action for an [`inject`](/library/inject.md#inject) call, on any [`Usage`](/library/types/enums.md#usage) class (button, key, or media). The discriminant is the wire byte. Convert with `as_u8()` and `from_u8(u8) -> Option<Action>`.

| Variant | Byte | Meaning |
| --- | --- | --- |
| `SoftRelease` | `0` | Drop the box's override, press or force; a physical hold stays down. |
| `Press` | `1` | Force the input down. |
| `ForceRelease` | `2` | Force the input up, masking a physical hold. |

#### RESULT THE PC SEES

The two releases differ only when the user physically holds the same input:

| Variant | User holds nothing | User is holding it |
| --- | --- | --- |
| `Press` | down | down |
| `SoftRelease` | up | down (physical wins) |
| `ForceRelease` | up | up (masks physical) |

## Class

_The class of a momentary usage_

```text
enum Class { Button, Key, Media }
```

The class byte of a [`Usage`](/library/types/enums.md#usage), shared by [`INJECT`](/native/commands/inject.md#inject), [`LOCK`](/native/commands/lock.md), and [`CATCH`](/native/commands/catch.md). Convert with `as_u8()` and `from_u8(u8) -> Option<Class>`.

| Variant | Byte | Meaning |
| --- | --- | --- |
| `Button` | `0` | A mouse button; id is a [`Button`](/library/types/enums.md#button) id (0=Left .. 4=Side2). |
| `Key` | `1` | A keyboard key; id is a HID keycode (0xE0 .. 0xE7 is a modifier). |
| `Media` | `2` | A media usage; id is a 16-bit Consumer usage. |

## Usage

_A momentary input: (class, id)_

```text
struct Usage { class: Class, id: u16 }
```

What [`inject`](/library/inject.md#inject) drives and [`LockTarget`](/library/types/enums.md#lock-target) locks: a mouse button, a keyboard key, or a media usage in one shape. A [`Button`](/library/types/enums.md#button), [`Key`](/library/types/structs.md#key), and [`MediaKey`](/library/types/structs.md#media-key) each `impl Into<Usage>`, so you pass one straight to any verb; build one by hand with `Usage::new(class, id)`.

| Field | Type | Meaning |
| --- | --- | --- |
| `class` | [`Class`](/library/types/enums.md#class) | The input class (button, key, or media). |
| `id` | `u16` | The class-specific id: a button id, a HID keycode, or a Consumer usage. |

#### EXAMPLE

```rust
use medius::{Button, Class, Key, Usage};

let from_button: Usage = Button::Left.into();      // Class::Button, id 0
let from_key: Usage = Key::A.into();               // Class::Key, id 0x04
let by_hand = Usage::new(Class::Media, 0x00E9);    // volume up
device.press(from_button)?;                         // press takes any impl Into<Usage>
```

## Motion

_A relative axis for move_axis_

```text
enum Motion { Cursor { dx: i16, dy: i16 }, Wheel(i16) }
```

What [`move_axis`](/library/move.md#move) drives: the cursor (carrying `dx` and `dy`) or the wheel (a single delta). Both span the full `i16` range. A lock names a single [`Axis`](/library/types/enums.md#axis) instead.

| Variant | Payload | Meaning |
| --- | --- | --- |
| `Cursor` | `{ dx: i16, dy: i16 }` | Relative pointer movement. |
| `Wheel` | `i16` | Relative scroll. |

## Axis

_A single relative axis_

```text
enum Axis { X, Y, Wheel }
```

One relative axis, the input kind that is genuinely mouse-hardware-specific. A [`lock_axis`](/library/lock.md#lock-axis) or a [`LockTarget::Axis`](/library/types/enums.md#lock-target) names one, with the sign given by a [`LockDirection`](/library/types/enums.md#lock-direction). Convert with `as_u16()`.

| Variant | id | Meaning |
| --- | --- | --- |
| `X` | `0` | The X cursor axis. |
| `Y` | `1` | The Y cursor axis. |
| `Wheel` | `2` | The wheel. |

## RebootTarget

_Which chip to restart, and how_

```text
enum RebootTarget { DeviceDownload, HostDownload, DeviceRun, HostRun }
```

Which chip a [`REBOOT`](/native/commands/admin.md#reboot) restarts, and into what mode. Convert with `as_u8()` and `from_u8(u8) -> Option<RebootTarget>`.

| Variant | Byte | Meaning |
| --- | --- | --- |
| `DeviceDownload` | `0` | Device chip into ROM download mode, ready to flash over the serial link. |
| `HostDownload` | `1` | Host chip into ROM download mode, ready to flash over its own USB. |
| `DeviceRun` | `2` | Restart the device chip and run its firmware. |
| `HostRun` | `3` | Restart the host chip and run its firmware. |

## EmitPace

_What paces injected motion_

```text
enum EmitPace { Learned, Interval, Fixed(u16) }
```

What sets the emit-rate ceiling for injected motion, passed to [`set_emit_pace`](/library/options.md#set-emit-pace) and returned in [`EmitPaceStatus`](/library/types/structs.md#emit-pace-status). It raises the ceiling only, so idle stays idle.

| Variant | Meaning |
| --- | --- |
| `Learned` | Pace to the mouse's learnt native report rate (the default). |
| `Interval` | Pace to the cloned mouse's declared poll rate (its `bInterval`). |
| `Fixed(u16)` | Pace to a fixed rate in Hz; snaps to `1000/n` and caps at 1 kHz. |

## LedTarget

_Which chip's status LED to drive_

```text
enum LedTarget { Device, Host, Both }
```

Which chip's LED a [`LED`](/native/commands/led.md) command drives. The discriminant is the wire `target` byte. Convert with `as_u8()` and `from_u8(u8) -> Option<LedTarget>`.

| Variant | Byte | Meaning |
| --- | --- | --- |
| `Device` | `0` | The device chip's own LED. |
| `Host` | `1` | The host chip's LED, relayed over the inter-chip link. |
| `Both` | `2` | Both LEDs at once. |

## LedMode

_What to drive the LED to_

```text
enum LedMode { Auto, Off, Solid, Blink }
```

What a [`LED`](/native/commands/led.md) command drives the LED to; `Auto` hands it back to the box's status display. The discriminant is the wire `mode` byte. Convert with `as_u8()` and `from_u8(u8) -> Option<LedMode>`.

| Variant | Byte | Meaning |
| --- | --- | --- |
| `Auto` | `0` | Restore the chip's own status display. |
| `Off` | `1` | LED dark. |
| `Solid` | `2` | Lit steadily at the command's `level`. |
| `Blink` | `3` | Blinks at the command's `level`. |

## LockTarget

_What a lock acts on_

```text
enum LockTarget { Axis(Axis), Usage(Usage) }
```

What a [`LOCK`](/native/commands/lock.md) command blocks: a relative [`Axis`](/library/types/enums.md#axis) or a momentary [`Usage`](/library/types/enums.md#usage) (a button, key, or media usage). An `Axis` and any `impl Into<Usage>` each convert `Into<LockTarget>`, so you pass one straight to [`lock`](/library/lock.md#lock). A button locks exactly like a key.

| Variant | Payload | Locked by |
| --- | --- | --- |
| `Axis` | [`Axis`](/library/types/enums.md#axis) | The sign, a [`LockDirection`](/library/types/enums.md#lock-direction) of positive, negative, or both. |
| `Usage` | [`Usage`](/library/types/enums.md#usage) | The press or release edge, a [`LockDirection`](/library/types/enums.md#lock-direction). |

## LockScope

_What a reported lock covers_

```text
enum LockScope { Target(LockTarget), Blanket(Class) }
```

What a [`LockEntry`](/library/types/structs.md#lock-entry) in a [`query_locks`](/library/requests.md#query-locks) reply covers: one specific [`LockTarget`](/library/types/enums.md#lock-target), or a whole-class blanket that locks every usage of a [`Class`](/library/types/enums.md#class) at once.

| Variant | Payload | Covers |
| --- | --- | --- |
| `Target` | [`LockTarget`](/library/types/enums.md#lock-target) | A specific axis or usage. |
| `Blanket` | [`Class`](/library/types/enums.md#class) | Every button, key, or media usage of the class. |

## LockDirection

_Which way or which edge to block_

```text
enum LockDirection { Both, Positive, Negative }
```

Which side of an input a [`LOCK`](/native/commands/lock.md) blocks. For an axis or the wheel it's a sign; for a usage (button, key, or media) it's an edge. The discriminant is the wire `direction` byte. Convert with `as_u8()` and `from_u8(u8) -> Option<LockDirection>`.

| Variant | Byte | Meaning |
| --- | --- | --- |
| `Both` | `0` | Both signs, or press and release. |
| `Positive` | `1` | Axis positive (`+`), or usage press. |
| `Negative` | `2` | Axis negative (`-`), or usage release. |

## Blanket

_A whole-group lock selector_

```text
enum Blanket { Aim, Wheel, Buttons, Keys, Media }
```

A whole input group: which one [`lock_all`](/library/lock.md#lock-all) / [`unlock_all`](/library/lock.md#lock-all) block in one call, and the members of a clip's [`ClipSettings`](/library/types/structs.md#clip-settings) auto-lock.

| Variant | Meaning |
| --- | --- |
| `Aim` | The X and Y cursor axes. |
| `Wheel` | The wheel. |
| `Buttons` | Every mouse button. |
| `Keys` | Every keyboard key and modifier. |
| `Media` | Every media (Consumer) usage. |

## LogLevel

_Severity tag on a log line_

```text
enum LogLevel { Error, Warn, Info, Debug, Verbose }
```

The severity tag on a [`LogLine`](/library/types/structs.md#log-line). `from_u8(u8)` is infallible: an unknown byte falls back to `Info`.

| Variant | Byte | Meaning |
| --- | --- | --- |
| `Error` | `0` | A failure the box could not recover from. |
| `Warn` | `1` | Something off that the box handled. |
| `Info` | `2` | Normal operational notices. |
| `Debug` | `3` | Detail for diagnosing a problem. |
| `Verbose` | `4` | The finest-grained trace output. |

## CatchEvent

_One physical-input event off the stream_

```text
enum CatchEvent { Motion(MotionEvent), Usages(UsageSnapshot) }
```

What an [`EventStream`](/library/catch.md#event-stream) yields, captured before lock suppression or injection. A relative axis is `Motion`; a held-usage snapshot (buttons, keys, or media, all one shape) is `Usages`. Match on the variant.

| Variant | Payload | Raised by |
| --- | --- | --- |
| `Motion` | [`MotionEvent`](/library/types/structs.md#motion-event) | A cursor or wheel change (the `MOTION` / `WHEEL` classes). |
| `Usages` | [`UsageSnapshot`](/library/types/structs.md#usage-snapshot) | A button, key, or media change (the `BUTTONS` / `KEYS` / `MEDIA` classes). |

## ClipState

_The buffered-clip lifecycle state_

```text
enum ClipState { Idle, Playing, Paused, Faulted }
```

The device-side clip state on [`ClipStatus::state`](/library/types/structs.md#clip-status), from [`ClipHandle::query_status()`](/library/requests.md#clip-status).

| Variant | Byte | Meaning |
| --- | --- | --- |
| `Idle` | `0` | No clip playing (empty, or a loaded clip parked at its start). |
| `Playing` | `1` | Draining the ring, one entry per native frame. |
| `Paused` | `2` | Held mid-clip, keeping the cursor and any held input; resumes from the same spot. |
| `Faulted` | `3` | An append was dropped or the ring overflowed; recover with `clear`. |

## Edge

_Which edge fires a clip trigger_

```text
enum Edge { Both, Press, Release }
```

Which edge of a bound usage fires a [`ClipTrigger`](/library/types/structs.md#clip-trigger): its press, its release, or either. It shares wire values with [`LockDirection`](/library/types/enums.md#lock-direction).

| Variant | Byte | Meaning |
| --- | --- | --- |
| `Both` | `0` | Fire on either edge. |
| `Press` | `1` | Fire on the press edge. |
| `Release` | `2` | Fire on the release edge. |

## ClipAction

_What a fired clip trigger does_

```text
enum ClipAction { Start, Stop, Pause, Resume, Restart, Toggle }
```

What a bound [`ClipTrigger`](/library/types/structs.md#clip-trigger) does to the clip when its edge fires. The discriminant doubles as the [`CLIP_CTRL`](/native/commands/clip.md#ctrl) op byte for the same action.

| Variant | Byte | Meaning |
| --- | --- | --- |
| `Start` | `0` | Start playback from the ring's head. |
| `Stop` | `1` | Stop playback and rewind to the head. |
| `Pause` | `2` | Hold playback mid-clip. |
| `Resume` | `3` | Continue a paused clip from where it stopped. |
| `Restart` | `4` | Rewind to the head and play from the start. |
| `Toggle` | `5` | Start if idle, stop if playing. |