| 1 | /** |
| 2 | * @file mouse.h |
| 3 | * |
| 4 | * Mouse encoding module - encode mouse events into terminal escape sequences. |
| 5 | */ |
| 6 | |
| 7 | #ifndef GHOSTTY_VT_MOUSE_H |
| 8 | #define GHOSTTY_VT_MOUSE_H |
| 9 | |
| 10 | /** @defgroup mouse Mouse Encoding |
| 11 | * |
| 12 | * Utilities for encoding mouse events into terminal escape sequences, |
| 13 | * supporting X10, UTF-8, SGR, URxvt, and SGR-Pixels mouse protocols. |
| 14 | * |
| 15 | * ## Basic Usage |
| 16 | * |
| 17 | * 1. Create an encoder instance with ghostty_mouse_encoder_new(). |
| 18 | * 2. Configure encoder options with ghostty_mouse_encoder_setopt() or |
| 19 | * ghostty_mouse_encoder_setopt_from_terminal(). |
| 20 | * 3. For each mouse event: |
| 21 | * - Create a mouse event with ghostty_mouse_event_new(). |
| 22 | * - Set event properties (action, button, modifiers, position). |
| 23 | * - Encode with ghostty_mouse_encoder_encode(). |
| 24 | * - Free the event with ghostty_mouse_event_free() or reuse it. |
| 25 | * 4. Free the encoder with ghostty_mouse_encoder_free() when done. |
| 26 | * |
| 27 | * For a complete working example, see example/c-vt-encode-mouse in the |
| 28 | * repository. |
| 29 | * |
| 30 | * ## Example |
| 31 | * |
| 32 | * @snippet c-vt-encode-mouse/src/main.c mouse-encode |
| 33 | * |
| 34 | * ## Example: Encoding with Terminal State |
| 35 | * |
| 36 | * When you have a GhosttyTerminal, you can sync its tracking mode and |
| 37 | * output format into the encoder automatically: |
| 38 | * |
| 39 | * @code{.c} |
| 40 | * // Create a terminal and feed it some VT data that enables mouse tracking |
| 41 | * GhosttyTerminal terminal; |
| 42 | * ghostty_terminal_new(NULL, &terminal, |
| 43 | * (GhosttyTerminalOptions){.cols = 80, .rows = 24, .max_scrollback = 0}); |
| 44 | * |
| 45 | * // Application might write data that enables mouse reporting, etc. |
| 46 | * ghostty_terminal_vt_write(terminal, vt_data, vt_len); |
| 47 | * |
| 48 | * // Create an encoder and sync its options from the terminal |
| 49 | * GhosttyMouseEncoder encoder; |
| 50 | * ghostty_mouse_encoder_new(NULL, &encoder); |
| 51 | * ghostty_mouse_encoder_setopt_from_terminal(encoder, terminal); |
| 52 | * |
| 53 | * // Encode a mouse event using the terminal-derived options |
| 54 | * char buf[128]; |
| 55 | * size_t written = 0; |
| 56 | * ghostty_mouse_encoder_encode(encoder, event, buf, sizeof(buf), &written); |
| 57 | * |
| 58 | * ghostty_mouse_encoder_free(encoder); |
| 59 | * ghostty_terminal_free(terminal); |
| 60 | * @endcode |
| 61 | * |
| 62 | * @{ |
| 63 | */ |
| 64 | |
| 65 | #include <ghostty/vt/mouse/event.h> |
| 66 | #include <ghostty/vt/mouse/encoder.h> |
| 67 | |
| 68 | /** @} */ |
| 69 | |
| 70 | #endif /* GHOSTTY_VT_MOUSE_H */ |