Module Input.KeySource

Keyboard keys.

Most keys map to dedicated constructors. Char handles all Unicode characters including control codes. Keypad keys (KP_*) are reported when the terminal sends distinct codes for keypad versus main keyboard. Unknown captures unrecognized Kitty protocol key codes for forward compatibility.

Keys

Sourcetype t =
  1. | Char of Uchar.t
    (*

    Unicode character, including control characters (e.g. Uchar.of_int 0x03 for Ctrl+C).

    *)
  2. | Enter
  3. | Line_feed
  4. | Tab
  5. | Backspace
  6. | Delete
  7. | Escape
  8. | Up
  9. | Down
  10. | Left
  11. | Right
  12. | Home
  13. | End
  14. | Page_up
  15. | Page_down
  16. | Insert
  17. | F of int
    (*

    Function key. Values outside [1;35] may appear from the Kitty protocol.

    *)
  18. | Print_screen
  19. | Pause
  20. | Menu
  21. | Scroll_lock
  22. | Media_play
  23. | Media_pause
  24. | Media_play_pause
  25. | Media_stop
  26. | Media_reverse
  27. | Media_fast_forward
  28. | Media_rewind
  29. | Media_next
  30. | Media_prev
  31. | Media_record
  32. | Volume_up
  33. | Volume_down
  34. | Volume_mute
  35. | Shift_left
  36. | Shift_right
  37. | Ctrl_left
  38. | Ctrl_right
  39. | Alt_left
  40. | Alt_right
  41. | Super_left
  42. | Super_right
  43. | Hyper_left
  44. | Hyper_right
  45. | Meta_left
  46. | Meta_right
  47. | Iso_level3_shift
  48. | Iso_level5_shift
  49. | Caps_lock
  50. | Num_lock
  51. | KP_0
    (*

    Keypad keys. Reported when the terminal sends distinct codes for keypad versus main keyboard.

    *)
  52. | KP_1
  53. | KP_2
  54. | KP_3
  55. | KP_4
  56. | KP_5
  57. | KP_6
  58. | KP_7
  59. | KP_8
  60. | KP_9
  61. | KP_decimal
  62. | KP_divide
  63. | KP_multiply
  64. | KP_subtract
  65. | KP_add
  66. | KP_enter
  67. | KP_equal
  68. | KP_separator
  69. | KP_begin
  70. | KP_left
  71. | KP_right
  72. | KP_up
  73. | KP_down
  74. | KP_page_up
  75. | KP_page_down
  76. | KP_home
  77. | KP_end
  78. | KP_insert
  79. | KP_delete
  80. | Unknown of int
    (*

    Unknown key code from Private Use Area or unmapped sequences. The int is the Kitty protocol key code.

    *)

The type for keyboard keys.

Predicates and comparisons

Sourceval equal : t -> t -> bool

equal a b is true iff a and b denote the same key.

For Char variants, compares Uchar.t values by code point. Unicode normalization is not performed: U+00E9 and U+0065 U+0301 are distinct.

Sourceval is_char : t -> bool

is_char k is true iff k is Char _.

Sourceval is_enter : t -> bool

is_enter k is true iff k is Enter.

Sourceval is_arrow : t -> bool

is_arrow k is true iff k is Up, Down, Left or Right.

Sourceval is_function : t -> bool

is_function k is true iff k is F _.

Sourceval is_ctrl_char : t -> bool

is_ctrl_char k is true iff k is a Char in the ASCII control range U+0000..U+001F or U+007F (DEL).

Formatting

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

pp formats keys for debugging.

Event types

Sourcetype event_type =
  1. | Press
  2. | Repeat
  3. | Release
    (*

    The type for key event types.

    Only available when the terminal supports the Kitty keyboard protocol. Legacy terminals always report Press.

    *)

Modifiers

Sourcetype modifier = {
  1. ctrl : bool;
    (*

    Control key held.

    *)
  2. alt : bool;
    (*

    Alt/Option key held.

    *)
  3. shift : bool;
    (*

    Shift key held.

    *)
  4. super : bool;
    (*

    Super/Windows/Command key held.

    *)
  5. hyper : bool;
    (*

    Hyper modifier key held.

    *)
  6. meta : bool;
    (*

    Meta modifier key held.

    *)
  7. caps_lock : bool;
    (*

    Caps Lock toggle is active.

    *)
  8. num_lock : bool;
    (*

    Num Lock toggle is active.

    *)
}

The type for modifier state.

Lock fields (caps_lock, num_lock) indicate toggle state, not whether the physical key is currently pressed.

Sourceval no_modifier : modifier

no_modifier is a modifier with all fields set to false. Useful as a base value: {no_modifier with ctrl = true}.

Sourceval equal_modifier : modifier -> modifier -> bool

equal_modifier a b is true iff all fields of a and b are equal.

Sourceval ctrl : modifier -> bool

ctrl m is m.ctrl.

Sourceval alt : modifier -> bool

alt m is m.alt.

Sourceval shift : modifier -> bool

shift m is m.shift.

Sourceval pp_modifier : Format.formatter -> modifier -> unit

pp_modifier formats modifier sets for debugging.

Key events

Sourcetype event = {
  1. key : t;
    (*

    The key.

    *)
  2. modifier : modifier;
    (*

    Active modifiers.

    *)
  3. event_type : event_type;
    (*

    Press, repeat or release.

    *)
  4. associated_text : string;
    (*

    UTF-8 text to insert. Populated by the Kitty protocol for text-producing keys and by the parser for legacy text bytes. Empty for non-text keys or when not provided.

    *)
  5. shifted_key : Uchar.t option;
    (*

    Key with Shift applied (Kitty protocol only). None on legacy terminals.

    *)
  6. base_key : Uchar.t option;
    (*

    Key without modifiers (Kitty protocol only). None on legacy terminals.

    *)
}

The type for key events. On legacy terminals event_type is always Press, and shifted_key and base_key are None.

Sourceval make : ?modifier:modifier -> ?event_type:event_type -> ?associated_text:string -> ?shifted_key:Uchar.t -> ?base_key:Uchar.t -> t -> event

make key is a key event for key with:

  • modifier defaults to no_modifier.
  • event_type defaults to Press.
  • associated_text defaults to "".
  • shifted_key defaults to None.
  • base_key defaults to None.
Sourceval of_char : ?modifier:modifier -> ?event_type:event_type -> ?associated_text:string -> ?shifted_key:Uchar.t -> ?base_key:Uchar.t -> char -> event

of_char c is like make with Char (Uchar.of_char c).

When associated_text is not provided it defaults to a single-character string for c. Uses shared strings for ASCII characters to reduce allocations.

Event predicates and comparisons

Sourceval equal_event : event -> event -> bool

equal_event a b is true iff all fields of a and b are structurally equal.

Sourceval pp_event : Format.formatter -> event -> unit

pp_event formats key events for debugging.