| 1 | /** |
| 2 | * @file key.h |
| 3 | * |
| 4 | * Key encoding module - encode key events into terminal escape sequences. |
| 5 | */ |
| 6 | |
| 7 | #ifndef GHOSTTY_VT_KEY_H |
| 8 | #define GHOSTTY_VT_KEY_H |
| 9 | |
| 10 | /** @defgroup key Key Encoding |
| 11 | * |
| 12 | * Utilities for encoding key events into terminal escape sequences, |
| 13 | * supporting both legacy encoding as well as Kitty Keyboard Protocol. |
| 14 | * |
| 15 | * ## Basic Usage |
| 16 | * |
| 17 | * 1. Create an encoder instance with ghostty_key_encoder_new() |
| 18 | * 2. Configure encoder options with ghostty_key_encoder_setopt() |
| 19 | * or ghostty_key_encoder_setopt_from_terminal() if you have a |
| 20 | * GhosttyTerminal. |
| 21 | * 3. For each key event: |
| 22 | * - Create a key event with ghostty_key_event_new() |
| 23 | * - Set event properties (action, key, modifiers, etc.) |
| 24 | * - Encode with ghostty_key_encoder_encode() |
| 25 | * - Free the event with ghostty_key_event_free() |
| 26 | * - Note: You can also reuse the same key event multiple times by |
| 27 | * changing its properties. |
| 28 | * 4. Free the encoder with ghostty_key_encoder_free() when done |
| 29 | * |
| 30 | * For a complete working example, see example/c-vt-encode-key in the |
| 31 | * repository. |
| 32 | * |
| 33 | * ## Example |
| 34 | * |
| 35 | * @snippet c-vt-encode-key/src/main.c key-encode |
| 36 | * |
| 37 | * ## Example: Encoding with Terminal State |
| 38 | * |
| 39 | * When you have a GhosttyTerminal, you can sync its modes (cursor key |
| 40 | * application, Kitty flags, etc.) into the encoder automatically: |
| 41 | * |
| 42 | * @code{.c} |
| 43 | * // Create a terminal and feed it some VT data that changes modes |
| 44 | * GhosttyTerminal terminal; |
| 45 | * ghostty_terminal_new(NULL, &terminal, |
| 46 | * (GhosttyTerminalOptions){.cols = 80, .rows = 24, .max_scrollback = 0}); |
| 47 | * |
| 48 | * // Application might write data that enables Kitty keyboard protocol, etc. |
| 49 | * ghostty_terminal_vt_write(terminal, vt_data, vt_len); |
| 50 | * |
| 51 | * // Create an encoder and sync its options from the terminal |
| 52 | * GhosttyKeyEncoder encoder; |
| 53 | * ghostty_key_encoder_new(NULL, &encoder); |
| 54 | * ghostty_key_encoder_setopt_from_terminal(encoder, terminal); |
| 55 | * |
| 56 | * // Encode a key event using the terminal-derived options |
| 57 | * char buf[128]; |
| 58 | * size_t written = 0; |
| 59 | * ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written); |
| 60 | * |
| 61 | * ghostty_key_encoder_free(encoder); |
| 62 | * ghostty_terminal_free(terminal); |
| 63 | * @endcode |
| 64 | * |
| 65 | * @{ |
| 66 | */ |
| 67 | |
| 68 | #include <ghostty/vt/key/event.h> |
| 69 | #include <ghostty/vt/key/encoder.h> |
| 70 | |
| 71 | /** @} */ |
| 72 | |
| 73 | #endif /* GHOSTTY_VT_KEY_H */ |