Input (p.matrix.0.1.0.doc.matrix.input.Input)

Event model

The event type t covers user-facing input. Capability responses are reported separately as Caps.event values so applications can handle input and capability detection independently.

Parsing

Create a Parser and feed it raw terminal bytes:

  let p = Input.Parser.create () in
  Input.Parser.feed p buf 0 len ~now ~on_event:handle_event
    ~on_caps:handle_caps

Escape sequences may arrive fragmented across reads; the parser buffers partial sequences until they complete or time out. Ambiguous sequences (lone Escape vs. Alt+key) use a 50ms timeout; clearly incomplete sequences (CSI, OSC) use 100ms. Call Parser.drain after Parser.deadline to emit pending events.

Warning. The parser is not thread-safe; use one instance per input source.

Key bindings

Keymap maps key combinations to application commands:

  let km =
    Input.Keymap.empty
    |> Input.Keymap.add_char ~ctrl:true 'q' `Quit
    |> Input.Keymap.add Input.Key.Enter `Submit
  in
  match Input.Keymap.find km event with
  | Some `Quit -> exit 0
  | Some `Submit -> submit ()
  | None -> ()

Keys and modifiers

Sourcemodule Key : sig ... end

Keyboard keys.

Mouse

Sourcemodule Mouse : sig ... end

Mouse buttons and motion events.

Terminal capabilities

Sourcemodule Caps : sig ... end

Terminal capability responses.

Events

Sourcetype t =

| Key of Key.event
(*
Keyboard input.
*)
| Mouse of Mouse.event
(*
Mouse button or motion.
*)
| Scroll of int * int * Mouse.scroll_direction * int * Key.modifier
(*
Scroll (x, y, dir, delta, mods) is a scroll wheel event at (x, y) with direction dir, step delta (usually 1), and modifiers mods. Coordinates are 0-based. Normalizes wheel actions across terminal protocols (SGR, URXVT, X10) into a single event.
*)
| Resize of int * int
(*
Resize (width, height) is a terminal resize.
*)
| Focus
(*
Terminal gained focus.
*)
| Blur
(*
Terminal lost focus.
*)
| Paste of string
(*
Paste text is bracketed paste content with ANSI escape sequences stripped. Empty payloads are dropped by the parser.
*)
| Clipboard of string * string
(*
Clipboard (selection, data) is an OSC 52 clipboard response. data is base64-decoded when possible, verbatim otherwise.
*)
| Osc of int * string
(*
Osc (number, payload) is an unhandled OSC sequence. payload is the raw text between introducer and terminator with no sanitization.
*)

The type for terminal input events.

Predicates and comparisons

Sourceval equal : t -> t -> bool

equal a b is true iff a and b are semantically equal.

For Key events only the key and modifier fields are compared; event_type, associated_text, shifted_key and base_key are ignored. All other variants compare fields structurally.

See equal_full for full structural equality.

Sourceval equal_full : t -> t -> bool

equal_full a b is true iff all fields of a and b are structurally equal. Unlike equal, this compares all fields of Key events including event_type and associated_text.

Formatting

Sourceval pp : Format.formatter -> t -> unit

pp formats events for debugging.

Constructors

Source

val key : 
  ?modifier:Key.modifier ->
  ?event_type:Key.event_type ->
  ?associated_text:string ->
  ?shifted_key:Uchar.t ->
  ?base_key:Uchar.t ->
  Key.t ->
  t

key k is Key (Key.make k) with the given optional arguments. See Key.make for defaults.

Source

val char : 
  ?modifier:Key.modifier ->
  ?event_type:Key.event_type ->
  ?associated_text:string ->
  ?shifted_key:Uchar.t ->
  ?base_key:Uchar.t ->
  char ->
  t

char c is Key (Key.of_char c) with the given optional arguments. See Key.of_char for defaults.

Source

val key_event : 
  ?modifier:Key.modifier ->
  ?event_type:Key.event_type ->
  ?associated_text:string ->
  ?shifted_key:Uchar.t ->
  ?base_key:Uchar.t ->
  Key.t ->
  Key.event

key_event k is Key.make k. Alias useful when you need the raw Key.event without wrapping in t.

Source

val char_event : 
  ?modifier:Key.modifier ->
  ?event_type:Key.event_type ->
  ?associated_text:string ->
  ?shifted_key:Uchar.t ->
  ?base_key:Uchar.t ->
  char ->
  Key.event

char_event c is Key.of_char c.

Source

val press : 
  ?modifier:Key.modifier ->
  ?associated_text:string ->
  ?shifted_key:Uchar.t ->
  ?base_key:Uchar.t ->
  Key.t ->
  Key.event

press k is Key.make ~event_type:Press k.

Source

val repeat : 
  ?modifier:Key.modifier ->
  ?associated_text:string ->
  ?shifted_key:Uchar.t ->
  ?base_key:Uchar.t ->
  Key.t ->
  Key.event

repeat k is Key.make ~event_type:Repeat k.

Source

val release : 
  ?modifier:Key.modifier ->
  ?associated_text:string ->
  ?shifted_key:Uchar.t ->
  ?base_key:Uchar.t ->
  Key.t ->
  Key.event

release k is Key.make ~event_type:Release k.

Sourceval mouse_press : ?modifier:Key.modifier -> int -> int -> Mouse.button -> t

mouse_press x y button is Mouse (Button_press (x, y, button, modifier)). modifier defaults to Key.no_modifier.

Sourceval mouse_release : ?modifier:Key.modifier -> int -> int -> Mouse.button -> t

mouse_release x y button is Mouse (Button_release (x, y, button, modifier)). modifier defaults to Key.no_modifier.

Source

val mouse_motion : 
  ?modifier:Key.modifier ->
  int ->
  int ->
  Mouse.button_state ->
  t

mouse_motion x y state is Mouse (Motion (x, y, state, modifier)). modifier defaults to Key.no_modifier.

Helpers

Sourceval match_ctrl_char : t -> char option

match_ctrl_char e is Some c when e is a Key event with modifier.ctrl = true and the key is an ASCII Char (code point < 0x80). None otherwise.

Sourceval is_scroll : t -> bool

is_scroll e is true iff e is a Scroll event or a Mouse event with a wheel button (Wheel_up, Wheel_down, Wheel_left, Wheel_right).

Sourceval is_drag : t -> bool

is_drag e is true iff e is a Mouse Motion event with at least one primary button pressed.

Sourcemodule Keymap : sig ... end

Key binding maps. See Keymap.

Sourcemodule Parser : sig ... end

Incremental input parser. See Parser.