1/**
2 * @file screen.h
3 *
4 * Terminal screen cell and row types.
5 */
6
7#ifndef GHOSTTY_VT_SCREEN_H
8#define GHOSTTY_VT_SCREEN_H
9
10#include <stdbool.h>
11#include <stdint.h>
12#include <ghostty/vt/color.h>
13#include <ghostty/vt/types.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19/** @defgroup screen Screen
20 *
21 * Terminal screen cell and row types.
22 *
23 * These types represent the contents of a terminal screen. A GhosttyCell
24 * is a single grid cell and a GhosttyRow is a single row. Both are opaque
25 * values whose fields are accessed via ghostty_cell_get() and
26 * ghostty_row_get() respectively.
27 *
28 * @{
29 */
30
31/**
32 * Opaque cell value.
33 *
34 * Represents a single terminal cell. The internal layout is opaque and
35 * must be queried via ghostty_cell_get(). Obtain cell values from
36 * terminal query APIs.
37 *
38 * @ingroup screen
39 */
40typedef uint64_t GhosttyCell;
41
42/**
43 * Opaque row value.
44 *
45 * Represents a single terminal row. The internal layout is opaque and
46 * must be queried via ghostty_row_get(). Obtain row values from
47 * terminal query APIs.
48 *
49 * @ingroup screen
50 */
51typedef uint64_t GhosttyRow;
52
53/**
54 * Cell content tag.
55 *
56 * Describes what kind of content a cell holds.
57 *
58 * @ingroup screen
59 */
60typedef enum GHOSTTY_ENUM_TYPED {
61 /** A single codepoint (may be zero for empty). */
62 GHOSTTY_CELL_CONTENT_CODEPOINT = 0,
63
64 /** A codepoint that is part of a multi-codepoint grapheme cluster. */
65 GHOSTTY_CELL_CONTENT_CODEPOINT_GRAPHEME = 1,
66
67 /** No text; background color from palette. */
68 GHOSTTY_CELL_CONTENT_BG_COLOR_PALETTE = 2,
69
70 /** No text; background color as RGB. */
71 GHOSTTY_CELL_CONTENT_BG_COLOR_RGB = 3,
72 GHOSTTY_CELL_CONTENT_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
73} GhosttyCellContentTag;
74
75/**
76 * Cell wide property.
77 *
78 * Describes the width behavior of a cell.
79 *
80 * @ingroup screen
81 */
82typedef enum GHOSTTY_ENUM_TYPED {
83 /** Not a wide character, cell width 1. */
84 GHOSTTY_CELL_WIDE_NARROW = 0,
85
86 /** Wide character, cell width 2. */
87 GHOSTTY_CELL_WIDE_WIDE = 1,
88
89 /** Spacer after wide character. Do not render. */
90 GHOSTTY_CELL_WIDE_SPACER_TAIL = 2,
91
92 /** Spacer at end of soft-wrapped line for a wide character. */
93 GHOSTTY_CELL_WIDE_SPACER_HEAD = 3,
94 GHOSTTY_CELL_WIDE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
95} GhosttyCellWide;
96
97/**
98 * Semantic content type of a cell.
99 *
100 * Set by semantic prompt sequences (OSC 133) to distinguish between
101 * command output, user input, and shell prompt text.
102 *
103 * @ingroup screen
104 */
105typedef enum GHOSTTY_ENUM_TYPED {
106 /** Regular output content, such as command output. */
107 GHOSTTY_CELL_SEMANTIC_OUTPUT = 0,
108
109 /** Content that is part of user input. */
110 GHOSTTY_CELL_SEMANTIC_INPUT = 1,
111
112 /** Content that is part of a shell prompt. */
113 GHOSTTY_CELL_SEMANTIC_PROMPT = 2,
114 GHOSTTY_CELL_SEMANTIC_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
115} GhosttyCellSemanticContent;
116
117/**
118 * Cell data types.
119 *
120 * These values specify what type of data to extract from a cell
121 * using `ghostty_cell_get`.
122 *
123 * @ingroup screen
124 */
125typedef enum GHOSTTY_ENUM_TYPED {
126 /** Invalid data type. Never results in any data extraction. */
127 GHOSTTY_CELL_DATA_INVALID = 0,
128
129 /**
130 * The codepoint of the cell (0 if empty or bg-color-only).
131 *
132 * Output type: uint32_t *
133 */
134 GHOSTTY_CELL_DATA_CODEPOINT = 1,
135
136 /**
137 * The content tag describing what kind of content is in the cell.
138 *
139 * Output type: GhosttyCellContentTag *
140 */
141 GHOSTTY_CELL_DATA_CONTENT_TAG = 2,
142
143 /**
144 * The wide property of the cell.
145 *
146 * Output type: GhosttyCellWide *
147 */
148 GHOSTTY_CELL_DATA_WIDE = 3,
149
150 /**
151 * Whether the cell has text to render.
152 *
153 * Output type: bool *
154 */
155 GHOSTTY_CELL_DATA_HAS_TEXT = 4,
156
157 /**
158 * Whether the cell has non-default styling.
159 *
160 * Output type: bool *
161 */
162 GHOSTTY_CELL_DATA_HAS_STYLING = 5,
163
164 /**
165 * The style ID for the cell (for use with style lookups).
166 *
167 * Output type: uint16_t *
168 */
169 GHOSTTY_CELL_DATA_STYLE_ID = 6,
170
171 /**
172 * Whether the cell has a hyperlink.
173 *
174 * Output type: bool *
175 */
176 GHOSTTY_CELL_DATA_HAS_HYPERLINK = 7,
177
178 /**
179 * Whether the cell is protected.
180 *
181 * Output type: bool *
182 */
183 GHOSTTY_CELL_DATA_PROTECTED = 8,
184
185 /**
186 * The semantic content type of the cell (from OSC 133).
187 *
188 * Output type: GhosttyCellSemanticContent *
189 */
190 GHOSTTY_CELL_DATA_SEMANTIC_CONTENT = 9,
191
192 /**
193 * The palette index for the cell's background color.
194 * Only valid when content_tag is GHOSTTY_CELL_CONTENT_BG_COLOR_PALETTE.
195 *
196 * Output type: GhosttyColorPaletteIndex *
197 */
198 GHOSTTY_CELL_DATA_COLOR_PALETTE = 10,
199
200 /**
201 * The RGB value for the cell's background color.
202 * Only valid when content_tag is GHOSTTY_CELL_CONTENT_BG_COLOR_RGB.
203 *
204 * Output type: GhosttyColorRgb *
205 */
206 GHOSTTY_CELL_DATA_COLOR_RGB = 11,
207 GHOSTTY_CELL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
208} GhosttyCellData;
209
210/**
211 * Row semantic prompt state.
212 *
213 * Indicates whether any cells in a row are part of a shell prompt,
214 * as reported by OSC 133 sequences.
215 *
216 * @ingroup screen
217 */
218typedef enum GHOSTTY_ENUM_TYPED {
219 /** No prompt cells in this row. */
220 GHOSTTY_ROW_SEMANTIC_NONE = 0,
221
222 /** Prompt cells exist and this is a primary prompt line. */
223 GHOSTTY_ROW_SEMANTIC_PROMPT = 1,
224
225 /** Prompt cells exist and this is a continuation line. */
226 GHOSTTY_ROW_SEMANTIC_PROMPT_CONTINUATION = 2,
227 GHOSTTY_ROW_SEMANTIC_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
228} GhosttyRowSemanticPrompt;
229
230/**
231 * Row data types.
232 *
233 * These values specify what type of data to extract from a row
234 * using `ghostty_row_get`.
235 *
236 * @ingroup screen
237 */
238typedef enum GHOSTTY_ENUM_TYPED {
239 /** Invalid data type. Never results in any data extraction. */
240 GHOSTTY_ROW_DATA_INVALID = 0,
241
242 /**
243 * Whether this row is soft-wrapped.
244 *
245 * Output type: bool *
246 */
247 GHOSTTY_ROW_DATA_WRAP = 1,
248
249 /**
250 * Whether this row is a continuation of a soft-wrapped row.
251 *
252 * Output type: bool *
253 */
254 GHOSTTY_ROW_DATA_WRAP_CONTINUATION = 2,
255
256 /**
257 * Whether any cells in this row have grapheme clusters.
258 *
259 * Output type: bool *
260 */
261 GHOSTTY_ROW_DATA_GRAPHEME = 3,
262
263 /**
264 * Whether any cells in this row have styling (may have false positives).
265 *
266 * Output type: bool *
267 */
268 GHOSTTY_ROW_DATA_STYLED = 4,
269
270 /**
271 * Whether any cells in this row have hyperlinks (may have false positives).
272 *
273 * Output type: bool *
274 */
275 GHOSTTY_ROW_DATA_HYPERLINK = 5,
276
277 /**
278 * The semantic prompt state of this row.
279 *
280 * Output type: GhosttyRowSemanticPrompt *
281 */
282 GHOSTTY_ROW_DATA_SEMANTIC_PROMPT = 6,
283
284 /**
285 * Whether this row contains a Kitty virtual placeholder.
286 *
287 * Output type: bool *
288 */
289 GHOSTTY_ROW_DATA_KITTY_VIRTUAL_PLACEHOLDER = 7,
290
291 /**
292 * Whether this row is dirty and requires a redraw.
293 *
294 * Output type: bool *
295 */
296 GHOSTTY_ROW_DATA_DIRTY = 8,
297 GHOSTTY_ROW_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
298} GhosttyRowData;
299
300/**
301 * Get data from a cell.
302 *
303 * Extracts typed data from the given cell based on the specified
304 * data type. The output pointer must be of the appropriate type for the
305 * requested data kind. Valid data types and output types are documented
306 * in the `GhosttyCellData` enum.
307 *
308 * @param cell The cell value
309 * @param data The type of data to extract
310 * @param out Pointer to store the extracted data (type depends on data parameter)
311 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
312 * data type is invalid
313 *
314 * @ingroup screen
315 */
316GHOSTTY_API GhosttyResult ghostty_cell_get(GhosttyCell cell,
317 GhosttyCellData data,
318 void *out);
319
320/**
321 * Get multiple data fields from a cell in a single call.
322 *
323 * Each element in the keys array specifies a data kind, and the
324 * corresponding element in the values array receives the result.
325 *
326 * Processing stops at the first error; on success out_written
327 * is set to count, on error it is set to the index of the
328 * failing key (i.e. the number of values successfully written).
329 *
330 * @param cell The cell value
331 * @param count Number of key/value pairs
332 * @param keys Array of data kinds to query
333 * @param values Array of output pointers (types must match each key's
334 * documented output type)
335 * @param[out] out_written On return, receives the number of values
336 * successfully written (may be NULL)
337 * @return GHOSTTY_SUCCESS if all queries succeed
338 *
339 * @ingroup screen
340 */
341GHOSTTY_API GhosttyResult ghostty_cell_get_multi(GhosttyCell cell,
342 size_t count,
343 const GhosttyCellData* keys,
344 void** values,
345 size_t* out_written);
346
347/**
348 * Get data from a row.
349 *
350 * Extracts typed data from the given row based on the specified
351 * data type. The output pointer must be of the appropriate type for the
352 * requested data kind. Valid data types and output types are documented
353 * in the `GhosttyRowData` enum.
354 *
355 * @param row The row value
356 * @param data The type of data to extract
357 * @param out Pointer to store the extracted data (type depends on data parameter)
358 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
359 * data type is invalid
360 *
361 * @ingroup screen
362 */
363GHOSTTY_API GhosttyResult ghostty_row_get(GhosttyRow row,
364 GhosttyRowData data,
365 void *out);
366
367/**
368 * Get multiple data fields from a row in a single call.
369 *
370 * Each element in the keys array specifies a data kind, and the
371 * corresponding element in the values array receives the result.
372 *
373 * Processing stops at the first error; on success out_written
374 * is set to count, on error it is set to the index of the
375 * failing key (i.e. the number of values successfully written).
376 *
377 * @param row The row value
378 * @param count Number of key/value pairs
379 * @param keys Array of data kinds to query
380 * @param values Array of output pointers (types must match each key's
381 * documented output type)
382 * @param[out] out_written On return, receives the number of values
383 * successfully written (may be NULL)
384 * @return GHOSTTY_SUCCESS if all queries succeed
385 *
386 * @ingroup screen
387 */
388GHOSTTY_API GhosttyResult ghostty_row_get_multi(GhosttyRow row,
389 size_t count,
390 const GhosttyRowData* keys,
391 void** values,
392 size_t* out_written);
393
394/** @} */
395
396#ifdef __cplusplus
397}
398#endif
399
400#endif /* GHOSTTY_VT_SCREEN_H */