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