@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
h 1,350 lines 46.4 KB
Raw
1 /**
2 * @file terminal.h
3 *
4 * Complete terminal emulator state and rendering.
5 */
6
7 #ifndef GHOSTTY_VT_TERMINAL_H
8 #define GHOSTTY_VT_TERMINAL_H
9
10 #include <stdbool.h>
11 #include <stddef.h>
12 #include <stdint.h>
13 #include <ghostty/vt/types.h>
14 #include <ghostty/vt/allocator.h>
15 #include <ghostty/vt/device.h>
16 #include <ghostty/vt/modes.h>
17 #include <ghostty/vt/size_report.h>
18 #include <ghostty/vt/grid_ref.h>
19 #include <ghostty/vt/kitty_graphics.h>
20 #include <ghostty/vt/screen.h>
21 #include <ghostty/vt/point.h>
22 #include <ghostty/vt/selection.h>
23 #include <ghostty/vt/style.h>
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 /** @defgroup terminal Terminal
30 *
31 * Complete terminal emulator state and rendering.
32 *
33 * A terminal instance manages the full emulator state including the screen,
34 * scrollback, cursor, styles, modes, and VT stream processing.
35 *
36 * Once a terminal session is up and running, you can configure a key encoder
37 * to write keyboard input via ghostty_key_encoder_setopt_from_terminal().
38 *
39 * ### Example: VT stream processing
40 * @snippet c-vt-stream/src/main.c vt-stream-init
41 * @snippet c-vt-stream/src/main.c vt-stream-write
42 *
43 * ## Effects
44 *
45 * By default, the terminal sequence processing with ghostty_terminal_vt_write()
46 * only process sequences that directly affect terminal state and
47 * ignores sequences that have side effect behavior or require responses.
48 * These sequences include things like bell characters, title changes, device
49 * attributes queries, and more. To handle these sequences, the embedder
50 * must configure "effects."
51 *
52 * Effects are callbacks that the terminal invokes in response to VT
53 * sequences processed during ghostty_terminal_vt_write(). They let the
54 * embedding application react to terminal-initiated events such as bell
55 * characters, title changes, device status report responses, and more.
56 *
57 * Each effect is registered with ghostty_terminal_set() using the
58 * corresponding `GhosttyTerminalOption` identifier. A `NULL` value
59 * pointer clears the callback and disables the effect.
60 *
61 * A userdata pointer can be attached via `GHOSTTY_TERMINAL_OPT_USERDATA`
62 * and is passed to every callback, allowing callers to route events
63 * back to their own application state without global variables.
64 * You cannot specify different userdata for different callbacks.
65 *
66 * All callbacks are invoked synchronously during
67 * ghostty_terminal_vt_write(). Callbacks **must not** call
68 * ghostty_terminal_vt_write() on the same terminal (no reentrancy).
69 * And callbacks must be very careful to not block for too long or perform
70 * expensive operations, since they are blocking further IO processing.
71 *
72 * The available effects are:
73 *
74 * | Option | Callback Type | Trigger |
75 * |-----------------------------------------|-----------------------------------|-------------------------------------------|
76 * | `GHOSTTY_TERMINAL_OPT_WRITE_PTY` | `GhosttyTerminalWritePtyFn` | Query responses written back to the pty |
77 * | `GHOSTTY_TERMINAL_OPT_BELL` | `GhosttyTerminalBellFn` | BEL character (0x07) |
78 * | `GHOSTTY_TERMINAL_OPT_TITLE_CHANGED` | `GhosttyTerminalTitleChangedFn` | Title change via OSC 0 / OSC 2 |
79 * | `GHOSTTY_TERMINAL_OPT_PWD_CHANGED` | `GhosttyTerminalPwdChangedFn` | Pwd change via OSC 7 / OSC 9 / OSC 1337 |
80 * | `GHOSTTY_TERMINAL_OPT_ENQUIRY` | `GhosttyTerminalEnquiryFn` | ENQ character (0x05) |
81 * | `GHOSTTY_TERMINAL_OPT_XTVERSION` | `GhosttyTerminalXtversionFn` | XTVERSION query (CSI > q) |
82 * | `GHOSTTY_TERMINAL_OPT_SIZE` | `GhosttyTerminalSizeFn` | XTWINOPS size query (CSI 14/16/18 t) |
83 * | `GHOSTTY_TERMINAL_OPT_COLOR_SCHEME` | `GhosttyTerminalColorSchemeFn` | Color scheme query (CSI ? 996 n) |
84 * | `GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES`| `GhosttyTerminalDeviceAttributesFn`| Device attributes query (CSI c / > c / = c)|
85 *
86 * ### Defining a write_pty callback
87 * @snippet c-vt-effects/src/main.c effects-write-pty
88 *
89 * ### Defining a bell callback
90 * @snippet c-vt-effects/src/main.c effects-bell
91 *
92 * ### Defining a title_changed callback
93 * @snippet c-vt-effects/src/main.c effects-title-changed
94 *
95 * ### Registering effects and processing VT data
96 * @snippet c-vt-effects/src/main.c effects-register
97 *
98 * ## Color Theme
99 *
100 * The terminal maintains a set of colors used for rendering: a foreground
101 * color, a background color, a cursor color, and a 256-color palette. Each
102 * of these has two layers: a **default** value set by the embedder, and an
103 * **override** value that programs running in the terminal can set via OSC
104 * escape sequences (e.g. OSC 10/11/12 for foreground/background/cursor,
105 * OSC 4 for individual palette entries).
106 *
107 * ### Default Colors
108 *
109 * Use ghostty_terminal_set() with the color options to configure the
110 * default colors. These represent the theme or configuration chosen by
111 * the embedder. Passing `NULL` clears the default, leaving the color
112 * unset.
113 *
114 * | Option | Input Type | Description |
115 * |-----------------------------------------|-------------------------|--------------------------------------|
116 * | `GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND` | `GhosttyColorRgb*` | Default foreground color |
117 * | `GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND` | `GhosttyColorRgb*` | Default background color |
118 * | `GHOSTTY_TERMINAL_OPT_COLOR_CURSOR` | `GhosttyColorRgb*` | Default cursor color |
119 * | `GHOSTTY_TERMINAL_OPT_COLOR_PALETTE` | `GhosttyColorRgb[256]*` | Default 256-color palette |
120 *
121 * For the palette, passing `NULL` resets to the built-in default palette.
122 * The palette set operation preserves any per-index OSC overrides that
123 * programs have applied; only unmodified indices are updated.
124 *
125 * ### Reading colors
126 *
127 * Use ghostty_terminal_get() to read colors. There are two variants for
128 * each color: the **effective** value (which returns the OSC override if
129 * one is active, otherwise the default) and the **default** value (which
130 * ignores any OSC overrides).
131 *
132 * | Data | Output Type | Description |
133 * |---------------------------------------------------|-------------------------|------------------------------------------------|
134 * | `GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND` | `GhosttyColorRgb*` | Effective foreground (override or default) |
135 * | `GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND` | `GhosttyColorRgb*` | Effective background (override or default) |
136 * | `GHOSTTY_TERMINAL_DATA_COLOR_CURSOR` | `GhosttyColorRgb*` | Effective cursor (override or default) |
137 * | `GHOSTTY_TERMINAL_DATA_COLOR_PALETTE` | `GhosttyColorRgb[256]*` | Current palette (with any OSC overrides) |
138 * | `GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT` | `GhosttyColorRgb*` | Default foreground only (ignores OSC override) |
139 * | `GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT` | `GhosttyColorRgb*` | Default background only (ignores OSC override) |
140 * | `GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT` | `GhosttyColorRgb*` | Default cursor only (ignores OSC override) |
141 * | `GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT` | `GhosttyColorRgb[256]*` | Default palette only (ignores OSC overrides) |
142 *
143 * For foreground, background, and cursor colors, the getters return
144 * `GHOSTTY_NO_VALUE` if no color is configured (neither a default nor an
145 * OSC override). The palette getters always succeed since the palette
146 * always has a value (the built-in default if nothing else is set).
147 *
148 * ### Setting a color theme
149 * @snippet c-vt-colors/src/main.c colors-set-defaults
150 *
151 * ### Reading effective and default colors
152 * @snippet c-vt-colors/src/main.c colors-read
153 *
154 * ### Full example with OSC overrides
155 * @snippet c-vt-colors/src/main.c colors-main
156 *
157 * @{
158 */
159
160 /**
161 * Terminal initialization options.
162 *
163 * @ingroup terminal
164 */
165 typedef struct {
166 /** Terminal width in cells. Must be greater than zero. */
167 uint16_t cols;
168
169 /** Terminal height in cells. Must be greater than zero. */
170 uint16_t rows;
171
172 /** Maximum number of lines to keep in scrollback history. */
173 size_t max_scrollback;
174
175 // TODO: Consider ABI compatibility implications of this struct.
176 // We may want to artificially pad it significantly to support
177 // future options.
178 } GhosttyTerminalOptions;
179
180 /**
181 * Scroll viewport behavior tag.
182 *
183 * @ingroup terminal
184 */
185 typedef enum GHOSTTY_ENUM_TYPED {
186 /** Scroll to the top of the scrollback. */
187 GHOSTTY_SCROLL_VIEWPORT_TOP,
188
189 /** Scroll to the bottom (active area). */
190 GHOSTTY_SCROLL_VIEWPORT_BOTTOM,
191
192 /** Scroll by a delta amount (up is negative). */
193 GHOSTTY_SCROLL_VIEWPORT_DELTA,
194
195 /**
196 * Scroll to an absolute row offset from the top of the scrollable
197 * area. Row 0 is the top of the scrollback and the requested row
198 * becomes the first visible row of the viewport. The value is
199 * clamped so the viewport never scrolls beyond the top of the
200 * active area. If the terminal has no scrollback (e.g. the
201 * alternate screen is active), the viewport always remains on the
202 * active area.
203 *
204 * This is the same row space as the offset field of
205 * GhosttyTerminalScrollbar, so a scrollbar position obtained from
206 * GHOSTTY_TERMINAL_DATA_SCROLLBAR round-trips cleanly.
207 */
208 GHOSTTY_SCROLL_VIEWPORT_ROW,
209 GHOSTTY_SCROLL_VIEWPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
210 } GhosttyTerminalScrollViewportTag;
211
212 /**
213 * Scroll viewport value.
214 *
215 * @ingroup terminal
216 */
217 typedef union {
218 /** Scroll delta (only used with GHOSTTY_SCROLL_VIEWPORT_DELTA). Up is negative. */
219 intptr_t delta;
220
221 /** Absolute row offset (only used with GHOSTTY_SCROLL_VIEWPORT_ROW). */
222 size_t row;
223
224 /** Padding for ABI compatibility. Do not use. */
225 uint64_t _padding[2];
226 } GhosttyTerminalScrollViewportValue;
227
228 /**
229 * Tagged union for scroll viewport behavior.
230 *
231 * @ingroup terminal
232 */
233 typedef struct {
234 GhosttyTerminalScrollViewportTag tag;
235 GhosttyTerminalScrollViewportValue value;
236 } GhosttyTerminalScrollViewport;
237
238 /**
239 * Terminal screen identifier.
240 *
241 * Identifies which screen buffer is active in the terminal.
242 *
243 * @ingroup terminal
244 */
245 typedef enum GHOSTTY_ENUM_TYPED {
246 /** The primary (normal) screen. */
247 GHOSTTY_TERMINAL_SCREEN_PRIMARY = 0,
248
249 /** The alternate screen. */
250 GHOSTTY_TERMINAL_SCREEN_ALTERNATE = 1,
251 GHOSTTY_TERMINAL_SCREEN_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
252 } GhosttyTerminalScreen;
253
254 /**
255 * Visual style of the terminal cursor.
256 *
257 * @ingroup terminal
258 */
259 typedef enum GHOSTTY_ENUM_TYPED {
260 /** Bar cursor (DECSCUSR 5, 6). */
261 GHOSTTY_TERMINAL_CURSOR_STYLE_BAR = 0,
262
263 /** Block cursor (DECSCUSR 1, 2). */
264 GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK = 1,
265
266 /** Underline cursor (DECSCUSR 3, 4). */
267 GHOSTTY_TERMINAL_CURSOR_STYLE_UNDERLINE = 2,
268
269 /** Hollow block cursor. */
270 GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK_HOLLOW = 3,
271 GHOSTTY_TERMINAL_CURSOR_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
272 } GhosttyTerminalCursorStyle;
273
274 /**
275 * Scrollbar state for the terminal viewport.
276 *
277 * Represents the scrollable area dimensions needed to render a scrollbar.
278 *
279 * @ingroup terminal
280 */
281 typedef struct {
282 /** Total size of the scrollable area in rows. */
283 uint64_t total;
284
285 /** Offset into the total area that the viewport is at. */
286 uint64_t offset;
287
288 /** Length of the visible area in rows. */
289 uint64_t len;
290 } GhosttyTerminalScrollbar;
291
292 /**
293 * Callback function type for bell.
294 *
295 * Called when the terminal receives a BEL character (0x07).
296 *
297 * @param terminal The terminal handle
298 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
299 *
300 * @ingroup terminal
301 */
302 typedef void (*GhosttyTerminalBellFn)(GhosttyTerminal terminal,
303 void* userdata);
304
305 /**
306 * Callback function type for color scheme queries (CSI ? 996 n).
307 *
308 * Called when the terminal receives a color scheme device status report
309 * query. Return true and fill *out_scheme with the current color scheme,
310 * or return false to silently ignore the query.
311 *
312 * @param terminal The terminal handle
313 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
314 * @param[out] out_scheme Pointer to store the current color scheme
315 * @return true if the color scheme was filled, false to ignore the query
316 *
317 * @ingroup terminal
318 */
319 typedef bool (*GhosttyTerminalColorSchemeFn)(GhosttyTerminal terminal,
320 void* userdata,
321 GhosttyColorScheme* out_scheme);
322
323 /**
324 * Callback function type for device attributes queries (DA1/DA2/DA3).
325 *
326 * Called when the terminal receives a device attributes query (CSI c,
327 * CSI > c, or CSI = c). Return true and fill *out_attrs with the
328 * response data, or return false to silently ignore the query.
329 *
330 * The terminal uses whichever sub-struct (primary, secondary, tertiary)
331 * matches the request type, but all three should be filled for simplicity.
332 *
333 * @param terminal The terminal handle
334 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
335 * @param[out] out_attrs Pointer to store the device attributes response
336 * @return true if attributes were filled, false to ignore the query
337 *
338 * @ingroup terminal
339 */
340 typedef bool (*GhosttyTerminalDeviceAttributesFn)(GhosttyTerminal terminal,
341 void* userdata,
342 GhosttyDeviceAttributes* out_attrs);
343
344 /**
345 * Callback function type for enquiry (ENQ, 0x05).
346 *
347 * Called when the terminal receives an ENQ character. Return the
348 * response bytes as a GhosttyString. The memory must remain valid
349 * until the callback returns. Return a zero-length string to send
350 * no response.
351 *
352 * @param terminal The terminal handle
353 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
354 * @return The response bytes to write back to the pty
355 *
356 * @ingroup terminal
357 */
358 typedef GhosttyString (*GhosttyTerminalEnquiryFn)(GhosttyTerminal terminal,
359 void* userdata);
360
361 /**
362 * Callback function type for size queries (XTWINOPS).
363 *
364 * Called in response to XTWINOPS size queries (CSI 14/16/18 t).
365 * Return true and fill *out_size with the current terminal geometry,
366 * or return false to silently ignore the query.
367 *
368 * @param terminal The terminal handle
369 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
370 * @param[out] out_size Pointer to store the terminal size information
371 * @return true if size was filled, false to ignore the query
372 *
373 * @ingroup terminal
374 */
375 typedef bool (*GhosttyTerminalSizeFn)(GhosttyTerminal terminal,
376 void* userdata,
377 GhosttySizeReportSize* out_size);
378
379 /**
380 * Callback function type for title_changed.
381 *
382 * Called when the terminal title changes via escape sequences
383 * (e.g. OSC 0 or OSC 2). The new title can be queried from the
384 * terminal after the callback returns.
385 *
386 * @param terminal The terminal handle
387 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
388 *
389 * @ingroup terminal
390 */
391 typedef void (*GhosttyTerminalTitleChangedFn)(GhosttyTerminal terminal,
392 void* userdata);
393
394 /**
395 * Callback function type for pwd_changed.
396 *
397 * Called when the terminal pwd (current working directory) changes via
398 * escape sequences: OSC 7 (file:// URI), OSC 9 (ConEmu CurrentDir), or
399 * OSC 1337 CurrentDir (iTerm2). Use ghostty_terminal_get() with
400 * GHOSTTY_TERMINAL_DATA_PWD inside the callback to read the new value.
401 *
402 * The terminal stores whatever bytes the shell emitted, without parsing.
403 * That means for OSC 7 the value is the raw URI (typically file://...);
404 * for OSC 9/OSC 1337 it is typically a bare path. The embedder is
405 * responsible for decoding any URI scheme or host if it cares about them.
406 *
407 * The callback also fires when the shell clears the pwd (e.g. an empty
408 * OSC 7). In that case GHOSTTY_TERMINAL_DATA_PWD returns a zero-length
409 * string.
410 *
411 * @param terminal The terminal handle
412 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
413 *
414 * @ingroup terminal
415 */
416 typedef void (*GhosttyTerminalPwdChangedFn)(GhosttyTerminal terminal,
417 void* userdata);
418
419 /**
420 * Callback function type for write_pty.
421 *
422 * Called when the terminal needs to write data back to the pty, for
423 * example in response to a device status report or mode query. The
424 * data is only valid for the duration of the call; callers must copy
425 * it if it needs to persist.
426 *
427 * @param terminal The terminal handle
428 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
429 * @param data Pointer to the response bytes
430 * @param len Length of the response in bytes
431 *
432 * @ingroup terminal
433 */
434 typedef void (*GhosttyTerminalWritePtyFn)(GhosttyTerminal terminal,
435 void* userdata,
436 const uint8_t* data,
437 size_t len);
438
439 /**
440 * Callback function type for XTVERSION.
441 *
442 * Called when the terminal receives an XTVERSION query (CSI > q).
443 * Return the version string (e.g. "myterm 1.0") as a GhosttyString.
444 * The memory must remain valid until the callback returns. Return a
445 * zero-length string to report the default "libghostty" version.
446 *
447 * @param terminal The terminal handle
448 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
449 * @return The version string to report
450 *
451 * @ingroup terminal
452 */
453 typedef GhosttyString (*GhosttyTerminalXtversionFn)(GhosttyTerminal terminal,
454 void* userdata);
455
456 /**
457 * Terminal option identifiers.
458 *
459 * These values are used with ghostty_terminal_set() to configure
460 * terminal callbacks and associated state.
461 *
462 * @ingroup terminal
463 */
464 typedef enum GHOSTTY_ENUM_TYPED {
465 /**
466 * Opaque userdata pointer passed to all callbacks.
467 *
468 * Input type: void*
469 */
470 GHOSTTY_TERMINAL_OPT_USERDATA = 0,
471
472 /**
473 * Callback invoked when the terminal needs to write data back
474 * to the pty (e.g. in response to a DECRQM query or device
475 * status report). Set to NULL to ignore such sequences.
476 *
477 * Input type: GhosttyTerminalWritePtyFn
478 */
479 GHOSTTY_TERMINAL_OPT_WRITE_PTY = 1,
480
481 /**
482 * Callback invoked when the terminal receives a BEL character
483 * (0x07). Set to NULL to ignore bell events.
484 *
485 * Input type: GhosttyTerminalBellFn
486 */
487 GHOSTTY_TERMINAL_OPT_BELL = 2,
488
489 /**
490 * Callback invoked when the terminal receives an ENQ character
491 * (0x05). Set to NULL to send no response.
492 *
493 * Input type: GhosttyTerminalEnquiryFn
494 */
495 GHOSTTY_TERMINAL_OPT_ENQUIRY = 3,
496
497 /**
498 * Callback invoked when the terminal receives an XTVERSION query
499 * (CSI > q). Set to NULL to report the default "libghostty" string.
500 *
501 * Input type: GhosttyTerminalXtversionFn
502 */
503 GHOSTTY_TERMINAL_OPT_XTVERSION = 4,
504
505 /**
506 * Callback invoked when the terminal title changes via escape
507 * sequences (e.g. OSC 0 or OSC 2). Set to NULL to ignore title
508 * change events.
509 *
510 * Input type: GhosttyTerminalTitleChangedFn
511 */
512 GHOSTTY_TERMINAL_OPT_TITLE_CHANGED = 5,
513
514 /**
515 * Callback invoked in response to XTWINOPS size queries
516 * (CSI 14/16/18 t). Set to NULL to silently ignore size queries.
517 *
518 * Input type: GhosttyTerminalSizeFn
519 */
520 GHOSTTY_TERMINAL_OPT_SIZE = 6,
521
522 /**
523 * Callback invoked in response to a color scheme device status
524 * report query (CSI ? 996 n). Return true and fill the out pointer
525 * to report the current scheme, or return false to silently ignore.
526 * Set to NULL to ignore color scheme queries.
527 *
528 * Input type: GhosttyTerminalColorSchemeFn
529 */
530 GHOSTTY_TERMINAL_OPT_COLOR_SCHEME = 7,
531
532 /**
533 * Callback invoked in response to a device attributes query
534 * (CSI c, CSI > c, or CSI = c). Return true and fill the out
535 * pointer with response data, or return false to silently ignore.
536 * Set to NULL to ignore device attributes queries.
537 *
538 * Input type: GhosttyTerminalDeviceAttributesFn
539 */
540 GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES = 8,
541
542 /**
543 * Set the terminal title manually.
544 *
545 * The string data is copied into the terminal. A NULL value pointer
546 * clears the title (equivalent to setting an empty string).
547 *
548 * Input type: GhosttyString*
549 */
550 GHOSTTY_TERMINAL_OPT_TITLE = 9,
551
552 /**
553 * Set the terminal working directory manually.
554 *
555 * The string data is copied into the terminal. A NULL value pointer
556 * clears the pwd (equivalent to setting an empty string).
557 *
558 * Input type: GhosttyString*
559 */
560 GHOSTTY_TERMINAL_OPT_PWD = 10,
561
562 /**
563 * Set the default foreground color.
564 *
565 * A NULL value pointer clears the default (unset).
566 *
567 * Input type: GhosttyColorRgb*
568 */
569 GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND = 11,
570
571 /**
572 * Set the default background color.
573 *
574 * A NULL value pointer clears the default (unset).
575 *
576 * Input type: GhosttyColorRgb*
577 */
578 GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND = 12,
579
580 /**
581 * Set the default cursor color.
582 *
583 * A NULL value pointer clears the default (unset).
584 *
585 * Input type: GhosttyColorRgb*
586 */
587 GHOSTTY_TERMINAL_OPT_COLOR_CURSOR = 13,
588
589 /**
590 * Set the default 256-color palette.
591 *
592 * The value must point to an array of exactly 256 GhosttyColorRgb values.
593 * A NULL value pointer resets to the built-in default palette.
594 *
595 * Input type: GhosttyColorRgb[256]*
596 */
597 GHOSTTY_TERMINAL_OPT_COLOR_PALETTE = 14,
598
599 /**
600 * Set the Kitty image storage limit in bytes.
601 *
602 * Applied to all initialized screens (primary and alternate).
603 * A value of zero disables the Kitty graphics protocol entirely,
604 * deleting all stored images and placements. A NULL value pointer
605 * is equivalent to zero (disables). Has no effect when Kitty graphics
606 * are disabled at build time.
607 *
608 * Input type: uint64_t*
609 */
610 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT = 15,
611
612 /**
613 * Enable or disable Kitty image loading via the file medium.
614 *
615 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
616 * are disabled at build time.
617 *
618 * Input type: bool*
619 */
620 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_FILE = 16,
621
622 /**
623 * Enable or disable Kitty image loading via the temporary file medium.
624 *
625 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
626 * are disabled at build time.
627 *
628 * Input type: bool*
629 */
630 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_TEMP_FILE = 17,
631
632 /**
633 * Enable or disable Kitty image loading via the shared memory medium.
634 *
635 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
636 * are disabled at build time.
637 *
638 * Input type: bool*
639 */
640 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_SHARED_MEM = 18,
641
642 /**
643 * Set the maximum bytes the APC handler will buffer for all protocols.
644 * This prevents malicious input from causing unbounded memory allocation.
645 * A NULL value pointer removes all overrides, reverting to the built-in
646 * defaults.
647 *
648 * Input type: size_t*
649 */
650 GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES = 19,
651
652 /**
653 * Set the maximum bytes the APC handler will buffer for Kitty graphics
654 * protocol data. A NULL value pointer removes the override, reverting
655 * to the built-in default.
656 *
657 * Input type: size_t*
658 */
659 GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES_KITTY = 20,
660
661 /**
662 * Set the active screen selection.
663 *
664 * The value must point to a GhosttySelection whose grid references are
665 * valid for this terminal's active screen at the time of the call. The
666 * terminal copies the selection immediately and converts it to
667 * terminal-owned tracked state, so the GhosttySelection struct and its
668 * untracked grid references do not need to outlive this call.
669 *
670 * Passing NULL clears the active screen selection.
671 *
672 * Input type: GhosttySelection*
673 */
674 GHOSTTY_TERMINAL_OPT_SELECTION = 21,
675
676 /**
677 * Set the default cursor style used by DECSCUSR reset (CSI 0 q).
678 *
679 * A NULL value pointer resets to the built-in default block cursor.
680 *
681 * Input type: GhosttyTerminalCursorStyle*
682 */
683 GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_STYLE = 22,
684
685 /**
686 * Set whether the default cursor should blink when reset by DECSCUSR
687 * (CSI 0 q).
688 *
689 * A NULL value pointer resets to the built-in default of not blinking.
690 *
691 * Input type: bool*
692 */
693 GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_BLINK = 23,
694
695 /**
696 * Enable or disable Glyph Protocol APC handling.
697 *
698 * When disabled, Glyph Protocol APC sequences are ignored and no
699 * support/query/register/clear responses are emitted. Disabling also clears
700 * the terminal session's glyph glossary. A NULL value pointer is a no-op.
701 *
702 * Input type: bool*
703 */
704 GHOSTTY_TERMINAL_OPT_GLYPH_PROTOCOL = 24,
705
706 /**
707 * Callback invoked when the terminal pwd changes via escape
708 * sequences (OSC 7, OSC 9, or OSC 1337 CurrentDir). Set to NULL
709 * to ignore pwd change events.
710 *
711 * Input type: GhosttyTerminalPwdChangedFn
712 */
713 GHOSTTY_TERMINAL_OPT_PWD_CHANGED = 25,
714 GHOSTTY_TERMINAL_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
715 } GhosttyTerminalOption;
716
717 /**
718 * Terminal data types.
719 *
720 * These values specify what type of data to extract from a terminal
721 * using `ghostty_terminal_get`.
722 *
723 * @ingroup terminal
724 */
725 typedef enum GHOSTTY_ENUM_TYPED {
726 /** Invalid data type. Never results in any data extraction. */
727 GHOSTTY_TERMINAL_DATA_INVALID = 0,
728
729 /**
730 * Terminal width in cells.
731 *
732 * Output type: uint16_t *
733 */
734 GHOSTTY_TERMINAL_DATA_COLS = 1,
735
736 /**
737 * Terminal height in cells.
738 *
739 * Output type: uint16_t *
740 */
741 GHOSTTY_TERMINAL_DATA_ROWS = 2,
742
743 /**
744 * Cursor column position (0-indexed).
745 *
746 * Output type: uint16_t *
747 */
748 GHOSTTY_TERMINAL_DATA_CURSOR_X = 3,
749
750 /**
751 * Cursor row position within the active area (0-indexed).
752 *
753 * Output type: uint16_t *
754 */
755 GHOSTTY_TERMINAL_DATA_CURSOR_Y = 4,
756
757 /**
758 * Whether the cursor has a pending wrap (next print will soft-wrap).
759 *
760 * Output type: bool *
761 */
762 GHOSTTY_TERMINAL_DATA_CURSOR_PENDING_WRAP = 5,
763
764 /**
765 * The currently active screen.
766 *
767 * Output type: GhosttyTerminalScreen *
768 */
769 GHOSTTY_TERMINAL_DATA_ACTIVE_SCREEN = 6,
770
771 /**
772 * Whether the cursor is visible (DEC mode 25).
773 *
774 * Output type: bool *
775 */
776 GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE = 7,
777
778 /**
779 * Current Kitty keyboard protocol flags.
780 *
781 * Output type: GhosttyKittyKeyFlags * (uint8_t *)
782 */
783 GHOSTTY_TERMINAL_DATA_KITTY_KEYBOARD_FLAGS = 8,
784
785 /**
786 * Scrollbar state for the terminal viewport.
787 *
788 * This is amortized O(1): the total is maintained incrementally as
789 * the terminal is modified and the viewport offset is cached. The
790 * first read after the viewport moves to an arbitrary position that
791 * isn't an absolute row (e.g. scrolling to a selection) may cost
792 * O(pages) to compute the offset, after which it is cached again.
793 *
794 * There is intentionally no change notification for scroll state.
795 * Callers building scrollbars should poll this once per frame or
796 * per write batch and diff the result to detect changes; this is
797 * what Ghostty's own renderer does.
798 *
799 * Output type: GhosttyTerminalScrollbar *
800 */
801 GHOSTTY_TERMINAL_DATA_SCROLLBAR = 9,
802
803 /**
804 * The current SGR style of the cursor.
805 *
806 * This is the style that will be applied to newly printed characters.
807 *
808 * Output type: GhosttyStyle *
809 */
810 GHOSTTY_TERMINAL_DATA_CURSOR_STYLE = 10,
811
812 /**
813 * Whether any mouse tracking mode is active.
814 *
815 * Returns true if any of the mouse tracking modes (X10, normal, button,
816 * or any-event) are enabled.
817 *
818 * Output type: bool *
819 */
820 GHOSTTY_TERMINAL_DATA_MOUSE_TRACKING = 11,
821
822 /**
823 * The terminal title as set by escape sequences (e.g. OSC 0/2).
824 *
825 * Returns a borrowed string. The pointer is valid until the next call
826 * to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty
827 * string (len=0) is returned when no title has been set.
828 *
829 * Output type: GhosttyString *
830 */
831 GHOSTTY_TERMINAL_DATA_TITLE = 12,
832
833 /**
834 * The terminal's current working directory as set by escape sequences
835 * (e.g. OSC 7).
836 *
837 * Returns a borrowed string. The pointer is valid until the next call
838 * to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty
839 * string (len=0) is returned when no pwd has been set.
840 *
841 * Output type: GhosttyString *
842 */
843 GHOSTTY_TERMINAL_DATA_PWD = 13,
844
845 /**
846 * The total number of rows in the active screen including scrollback.
847 *
848 * Output type: size_t *
849 */
850 GHOSTTY_TERMINAL_DATA_TOTAL_ROWS = 14,
851
852 /**
853 * The number of scrollback rows (total rows minus viewport rows).
854 *
855 * Output type: size_t *
856 */
857 GHOSTTY_TERMINAL_DATA_SCROLLBACK_ROWS = 15,
858
859 /**
860 * The total width of the terminal in pixels.
861 *
862 * This is cols * cell_width_px as set by ghostty_terminal_resize().
863 *
864 * Output type: uint32_t *
865 */
866 GHOSTTY_TERMINAL_DATA_WIDTH_PX = 16,
867
868 /**
869 * The total height of the terminal in pixels.
870 *
871 * This is rows * cell_height_px as set by ghostty_terminal_resize().
872 *
873 * Output type: uint32_t *
874 */
875 GHOSTTY_TERMINAL_DATA_HEIGHT_PX = 17,
876
877 /**
878 * The effective foreground color (override or default).
879 *
880 * Returns GHOSTTY_NO_VALUE if no foreground color is set.
881 *
882 * Output type: GhosttyColorRgb *
883 */
884 GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND = 18,
885
886 /**
887 * The effective background color (override or default).
888 *
889 * Returns GHOSTTY_NO_VALUE if no background color is set.
890 *
891 * Output type: GhosttyColorRgb *
892 */
893 GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND = 19,
894
895 /**
896 * The effective cursor color (override or default).
897 *
898 * Returns GHOSTTY_NO_VALUE if no cursor color is set.
899 *
900 * Output type: GhosttyColorRgb *
901 */
902 GHOSTTY_TERMINAL_DATA_COLOR_CURSOR = 20,
903
904 /**
905 * The current 256-color palette.
906 *
907 * Output type: GhosttyColorRgb[256] *
908 */
909 GHOSTTY_TERMINAL_DATA_COLOR_PALETTE = 21,
910
911 /**
912 * The default foreground color (ignoring any OSC override).
913 *
914 * Returns GHOSTTY_NO_VALUE if no default foreground color is set.
915 *
916 * Output type: GhosttyColorRgb *
917 */
918 GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT = 22,
919
920 /**
921 * The default background color (ignoring any OSC override).
922 *
923 * Returns GHOSTTY_NO_VALUE if no default background color is set.
924 *
925 * Output type: GhosttyColorRgb *
926 */
927 GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT = 23,
928
929 /**
930 * The default cursor color (ignoring any OSC override).
931 *
932 * Returns GHOSTTY_NO_VALUE if no default cursor color is set.
933 *
934 * Output type: GhosttyColorRgb *
935 */
936 GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT = 24,
937
938 /**
939 * The default 256-color palette (ignoring any OSC overrides).
940 *
941 * Output type: GhosttyColorRgb[256] *
942 */
943 GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT = 25,
944
945 /**
946 * The Kitty image storage limit in bytes for the active screen.
947 *
948 * A value of zero means the Kitty graphics protocol is disabled.
949 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
950 *
951 * Output type: uint64_t *
952 */
953 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_STORAGE_LIMIT = 26,
954
955 /**
956 * Whether the file medium is enabled for Kitty image loading on the
957 * active screen.
958 *
959 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
960 *
961 * Output type: bool *
962 */
963 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_FILE = 27,
964
965 /**
966 * Whether the temporary file medium is enabled for Kitty image loading
967 * on the active screen.
968 *
969 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
970 *
971 * Output type: bool *
972 */
973 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_TEMP_FILE = 28,
974
975 /**
976 * Whether the shared memory medium is enabled for Kitty image loading
977 * on the active screen.
978 *
979 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
980 *
981 * Output type: bool *
982 */
983 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_SHARED_MEM = 29,
984
985 /**
986 * The Kitty graphics image storage for the active screen.
987 *
988 * Returns a borrowed pointer to the image storage. The pointer is valid
989 * until the next mutating terminal call (e.g. ghostty_terminal_vt_write()
990 * or ghostty_terminal_reset()).
991 *
992 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
993 *
994 * Output type: GhosttyKittyGraphics *
995 */
996 GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS = 30,
997
998 /**
999 * The active screen's current selection.
1000 *
1001 * On success, writes an untracked snapshot of the terminal-owned selection
1002 * to the caller-provided GhosttySelection. The GhosttySelection struct is
1003 * caller-owned and may be kept, but the grid references inside it are
1004 * untracked borrowed references into the active screen. They are only valid
1005 * until the next mutating terminal call, such as ghostty_terminal_set(),
1006 * ghostty_terminal_vt_write(), ghostty_terminal_resize(), or
1007 * ghostty_terminal_reset().
1008 *
1009 * Returns GHOSTTY_NO_VALUE when there is no active selection.
1010 *
1011 * Output type: GhosttySelection *
1012 */
1013 GHOSTTY_TERMINAL_DATA_SELECTION = 31,
1014
1015 /**
1016 * Whether the viewport is currently pinned to the active area.
1017 *
1018 * This is true when the viewport is following the active terminal area,
1019 * and false when the user has scrolled into history.
1020 *
1021 * Output type: bool *
1022 */
1023 GHOSTTY_TERMINAL_DATA_VIEWPORT_ACTIVE = 32,
1024 GHOSTTY_TERMINAL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
1025 } GhosttyTerminalData;
1026
1027 /**
1028 * Create a new terminal instance.
1029 *
1030 * @param allocator Pointer to allocator, or NULL to use the default allocator
1031 * @param terminal Pointer to store the created terminal handle
1032 * @param options Terminal initialization options
1033 * @return GHOSTTY_SUCCESS on success, or an error code on failure
1034 *
1035 * @ingroup terminal
1036 */
1037 GHOSTTY_API GhosttyResult ghostty_terminal_new(const GhosttyAllocator* allocator,
1038 GhosttyTerminal* terminal,
1039 GhosttyTerminalOptions options);
1040
1041 /**
1042 * Free a terminal instance.
1043 *
1044 * Releases all resources associated with the terminal. After this call,
1045 * the terminal handle becomes invalid and must not be used.
1046 *
1047 * @param terminal The terminal handle to free (may be NULL)
1048 *
1049 * @ingroup terminal
1050 */
1051 GHOSTTY_API void ghostty_terminal_free(GhosttyTerminal terminal);
1052
1053 /**
1054 * Perform a full reset of the terminal (RIS).
1055 *
1056 * Resets all terminal state back to its initial configuration, including
1057 * modes, scrollback, scrolling region, and screen contents. The terminal
1058 * dimensions are preserved.
1059 *
1060 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1061 *
1062 * @ingroup terminal
1063 */
1064 GHOSTTY_API void ghostty_terminal_reset(GhosttyTerminal terminal);
1065
1066 /**
1067 * Resize the terminal to the given dimensions.
1068 *
1069 * Changes the number of columns and rows in the terminal. The primary
1070 * screen will reflow content if wraparound mode is enabled; the alternate
1071 * screen does not reflow. If the dimensions are unchanged, this is a no-op.
1072 *
1073 * This also updates the terminal's pixel dimensions (used for image
1074 * protocols and size reports), disables synchronized output mode (allowed
1075 * by the spec so that resize results are shown immediately), and sends an
1076 * in-band size report if mode 2048 is enabled.
1077 *
1078 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1079 * @param cols New width in cells (must be greater than zero)
1080 * @param rows New height in cells (must be greater than zero)
1081 * @param cell_width_px Width of a single cell in pixels
1082 * @param cell_height_px Height of a single cell in pixels
1083 * @return GHOSTTY_SUCCESS on success, or an error code on failure
1084 *
1085 * @ingroup terminal
1086 */
1087 GHOSTTY_API GhosttyResult ghostty_terminal_resize(GhosttyTerminal terminal,
1088 uint16_t cols,
1089 uint16_t rows,
1090 uint32_t cell_width_px,
1091 uint32_t cell_height_px);
1092
1093 /**
1094 * Set an option on the terminal.
1095 *
1096 * Configures terminal callbacks and associated state such as the
1097 * write_pty callback and userdata pointer. The value is passed
1098 * directly for pointer types (callbacks, userdata) or as a pointer
1099 * to the value for non-pointer types (e.g. GhosttyString*).
1100 * NULL clears the option to its default.
1101 *
1102 * Callbacks are invoked synchronously during ghostty_terminal_vt_write().
1103 * Callbacks must not call ghostty_terminal_vt_write() on the same
1104 * terminal (no reentrancy).
1105 *
1106 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1107 * @param option The option to set
1108 * @param value Pointer to the value to set (type depends on the option),
1109 * or NULL to clear the option
1110 *
1111 * @ingroup terminal
1112 */
1113 GHOSTTY_API GhosttyResult ghostty_terminal_set(GhosttyTerminal terminal,
1114 GhosttyTerminalOption option,
1115 const void* value);
1116
1117 /**
1118 * Write VT-encoded data to the terminal for processing.
1119 *
1120 * Feeds raw bytes through the terminal's VT stream parser, updating
1121 * terminal state accordingly. By default, sequences that require output
1122 * (queries, device status reports) are silently ignored. Use
1123 * ghostty_terminal_set() with GHOSTTY_TERMINAL_OPT_WRITE_PTY to install
1124 * a callback that receives response data.
1125 *
1126 * This never fails. Any erroneous input or errors in processing the
1127 * input are logged internally but do not cause this function to fail
1128 * because this input is assumed to be untrusted and from an external
1129 * source; so the primary goal is to keep the terminal state consistent and
1130 * not allow malformed input to corrupt or crash.
1131 *
1132 * @param terminal The terminal handle
1133 * @param data Pointer to the data to write
1134 * @param len Length of the data in bytes
1135 *
1136 * @ingroup terminal
1137 */
1138 GHOSTTY_API void ghostty_terminal_vt_write(GhosttyTerminal terminal,
1139 const uint8_t* data,
1140 size_t len);
1141
1142 /**
1143 * Scroll the terminal viewport.
1144 *
1145 * Scrolls the terminal's viewport according to the given behavior.
1146 * When using GHOSTTY_SCROLL_VIEWPORT_DELTA, set the delta field in
1147 * the value union to specify the number of rows to scroll (negative
1148 * for up, positive for down). When using GHOSTTY_SCROLL_VIEWPORT_ROW,
1149 * set the row field to the absolute row offset from the top of the
1150 * scrollable area (the same row space as the offset field of
1151 * GhosttyTerminalScrollbar). For other behaviors, the value is ignored.
1152 *
1153 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1154 * @param behavior The scroll behavior as a tagged union
1155 *
1156 * @ingroup terminal
1157 */
1158 GHOSTTY_API void ghostty_terminal_scroll_viewport(GhosttyTerminal terminal,
1159 GhosttyTerminalScrollViewport behavior);
1160
1161 /**
1162 * Get the current value of a terminal mode.
1163 *
1164 * Returns the value of the mode identified by the given mode.
1165 *
1166 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1167 * @param mode The mode identifying the mode to query
1168 * @param[out] out_value On success, set to true if the mode is set, false
1169 * if it is reset
1170 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1171 * is NULL or the mode does not correspond to a known mode
1172 *
1173 * @ingroup terminal
1174 */
1175 GHOSTTY_API GhosttyResult ghostty_terminal_mode_get(GhosttyTerminal terminal,
1176 GhosttyMode mode,
1177 bool* out_value);
1178
1179 /**
1180 * Set the value of a terminal mode.
1181 *
1182 * Sets the mode identified by the given mode to the specified value.
1183 *
1184 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1185 * @param mode The mode identifying the mode to set
1186 * @param value true to set the mode, false to reset it
1187 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1188 * is NULL or the mode does not correspond to a known mode
1189 *
1190 * @ingroup terminal
1191 */
1192 GHOSTTY_API GhosttyResult ghostty_terminal_mode_set(GhosttyTerminal terminal,
1193 GhosttyMode mode,
1194 bool value);
1195
1196 /**
1197 * Get data from a terminal instance.
1198 *
1199 * Extracts typed data from the given terminal based on the specified
1200 * data type. The output pointer must be of the appropriate type for the
1201 * requested data kind. Valid data types and output types are documented
1202 * in the `GhosttyTerminalData` enum.
1203 *
1204 * @param terminal The terminal handle (may be NULL)
1205 * @param data The type of data to extract
1206 * @param out Pointer to store the extracted data (type depends on data parameter)
1207 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1208 * is NULL or the data type is invalid
1209 *
1210 * @ingroup terminal
1211 */
1212 GHOSTTY_API GhosttyResult ghostty_terminal_get(GhosttyTerminal terminal,
1213 GhosttyTerminalData data,
1214 void *out);
1215
1216 /**
1217 * Get multiple data fields from a terminal in a single call.
1218 *
1219 * This is an optimization over calling ghostty_terminal_get()
1220 * repeatedly, particularly useful in environments with high per-call
1221 * overhead such as FFI or Cgo.
1222 *
1223 * Each element in the keys array specifies a data kind, and the
1224 * corresponding element in the values array receives the result.
1225 * The type of each values[i] pointer must match the output type
1226 * documented for keys[i].
1227 *
1228 * Processing stops at the first error; on success out_written
1229 * is set to count, on error it is set to the index of the
1230 * failing key (i.e. the number of values successfully written).
1231 *
1232 * @param terminal The terminal handle (may be NULL)
1233 * @param count Number of key/value pairs
1234 * @param keys Array of data kinds to query
1235 * @param values Array of output pointers (types must match each key's
1236 * documented output type)
1237 * @param[out] out_written On return, receives the number of values
1238 * successfully written (may be NULL)
1239 * @return GHOSTTY_SUCCESS if all queries succeed
1240 *
1241 * @ingroup terminal
1242 */
1243 GHOSTTY_API GhosttyResult ghostty_terminal_get_multi(GhosttyTerminal terminal,
1244 size_t count,
1245 const GhosttyTerminalData* keys,
1246 void** values,
1247 size_t* out_written);
1248
1249 /**
1250 * Resolve a point in the terminal grid to a grid reference.
1251 *
1252 * Resolves the given point (which can be in active, viewport, screen,
1253 * or history coordinates) to a grid reference for that location. Use
1254 * ghostty_grid_ref_cell() and ghostty_grid_ref_row() to extract the cell
1255 * and row.
1256 *
1257 * Lookups using the `active` and `viewport` tags are fast. The `screen`
1258 * and `history` tags may require traversing the full scrollback page list
1259 * to resolve the y coordinate, so they can be expensive for large
1260 * scrollback buffers.
1261 *
1262 * This function isn't meant to be used as the core of render loop. It
1263 * isn't built to sustain the framerates needed for rendering large screens.
1264 * Use the render state API for that. This API is instead meant for less
1265 * strictly performance-sensitive use cases.
1266 *
1267 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1268 * @param point The point specifying which cell to look up
1269 * @param[out] out_ref On success, set to the grid reference at the given point (may be NULL)
1270 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1271 * is NULL or the point is out of bounds
1272 *
1273 * @ingroup terminal
1274 */
1275 GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref(GhosttyTerminal terminal,
1276 GhosttyPoint point,
1277 GhosttyGridRef *out_ref);
1278
1279 /**
1280 * Create an owned tracked grid reference for a terminal point.
1281 *
1282 * This is the tracked variant of ghostty_terminal_grid_ref(). The returned
1283 * handle follows the referenced cell as the terminal's page list is modified:
1284 * scrolling, pruning, resize/reflow, and other page-list operations update the
1285 * tracked reference automatically.
1286 *
1287 * The reference is attached to the terminal screen/page-list that is active at
1288 * creation time.
1289 *
1290 * If the point is outside the requested coordinate space, this returns
1291 * GHOSTTY_INVALID_VALUE and writes NULL to out_ref.
1292 *
1293 * The returned handle must be freed with ghostty_tracked_grid_ref_free(). If
1294 * the terminal is freed first, the handle remains valid only for
1295 * tracked-grid-ref APIs: it reports no value and can still be freed.
1296 *
1297 * @param terminal Terminal instance.
1298 * @param point Point to track.
1299 * @param[out] out_ref On success, receives the tracked reference handle.
1300 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if terminal,
1301 * point, or out_ref is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation
1302 * fails.
1303 *
1304 * @ingroup terminal
1305 */
1306 GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref_track(
1307 GhosttyTerminal terminal,
1308 GhosttyPoint point,
1309 GhosttyTrackedGridRef *out_ref);
1310
1311 /**
1312 * Convert a grid reference back to a point in the given coordinate system.
1313 *
1314 * This is the inverse of ghostty_terminal_grid_ref(): given a grid reference,
1315 * it returns the x/y coordinates in the requested coordinate system (active,
1316 * viewport, screen, or history).
1317 *
1318 * The grid reference must have been obtained from the same terminal instance.
1319 * Like all grid references, it is only valid until the next mutating terminal
1320 * call.
1321 *
1322 * Not every grid reference is representable in every coordinate system. For
1323 * example, a cell in scrollback history cannot be expressed in active
1324 * coordinates, and a cell that has scrolled off the visible area cannot be
1325 * expressed in viewport coordinates. In these cases, the function returns
1326 * GHOSTTY_NO_VALUE.
1327 *
1328 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1329 * @param ref Pointer to the grid reference to convert
1330 * @param tag The target coordinate system
1331 * @param[out] out On success, set to the coordinate in the requested system (may be NULL)
1332 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1333 * or ref is NULL/invalid, GHOSTTY_NO_VALUE if the ref falls outside
1334 * the requested coordinate system
1335 *
1336 * @ingroup terminal
1337 */
1338 GHOSTTY_API GhosttyResult ghostty_terminal_point_from_grid_ref(
1339 GhosttyTerminal terminal,
1340 const GhosttyGridRef *ref,
1341 GhosttyPointTag tag,
1342 GhosttyPointCoordinate *out);
1343
1344 /** @} */
1345
1346 #ifdef __cplusplus
1347 }
1348 #endif
1349
1350 #endif /* GHOSTTY_VT_TERMINAL_H */