libghostty VT

https://libghostty.tip.ghostty.org
Admin
libghostty-vt is a C library that provides a virtual terminal emulator with support for VT sequence...
Tokens:109,243
Snippets:906
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Terminal Formatting Example

Source: https://libghostty.tip.ghostty.org/c-vt-formatter_2src_2main_8c-example.html

Demonstrates creating a terminal, writing VT sequences, and formatting the resulting grid as plain text.

```c
#include <assert.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ghostty/vt.h>
int main() {
// Create a terminal with a small grid
GhosttyTerminal terminal;
GhosttyTerminalOptions opts = {
.cols = 80,
.rows = 24,
.max_scrollback = 0,
};
GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
assert(result == GHOSTTY_SUCCESS);
// Write VT-encoded content into the terminal to exercise various
// cursor movement and styling sequences.
const char *commands[] = {
"Line 1: Hello World!\r\n", // Simple text on row 1
"Line 2: \033[1mBold\033[0m and " // Bold text on row 2
"\033[4mUnderline\033[0m\r\n",
"Line 3: placeholder\r\n", // Will be overwritten below
"\033[3;1H", // CUP: move cursor back to row 3, col 1
"\033[2K", // EL: erase the entire line
"Line 3: Overwritten!\r\n", // Rewrite row 3 with new content
"\033[5;10H", // CUP: jump to row 5, col 10
"Placed at (5,10)", // Write at that position
"\033[1;72H", // CUP: jump to row 1, col 72
"RIGHT->", // Near the right edge of row 1
};
for (size_t i = 0; i < sizeof(commands) / sizeof(commands[0]); i++) {
ghostty_terminal_vt_write(terminal, (const uint8_t *)commands[i],
strlen(commands[i]));
}
// Create a plain-text formatter for the terminal
GhosttyFormatterTerminalOptions fmt_opts = GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
fmt_opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
fmt_opts.trim = true;
GhosttyFormatter formatter;
result = ghostty_formatter_terminal_new(NULL, &formatter, terminal, fmt_opts);
assert(result == GHOSTTY_SUCCESS);
// Format into an allocated buffer
uint8_t *buf = NULL;
size_t len = 0;
result = ghostty_formatter_format_alloc(formatter, NULL, &buf, &len);
assert(result == GHOSTTY_SUCCESS);
// Print the formatted output
printf("Formatted output (%zu bytes):\n", len);
fwrite(buf, 1, len, stdout);
printf("\n");
// Clean up
ghostty_free(NULL, buf, len);
ghostty_formatter_free(formatter);
ghostty_terminal_free(terminal);
return 0;
}
```

--------------------------------

### Install callback and send PNG image

Source: https://libghostty.tip.ghostty.org/group__sys.html

Registers the PNG decoder, initializes a terminal, and sends a Kitty graphics command to display an inline image.

```c
int main() {
/* Install the PNG decoder via the sys interface. */
int decode_count = 0;
ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, &decode_count);
ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, (const void*)decode_png);
/* Create a terminal with Kitty graphics enabled. */
GhosttyTerminal terminal = NULL;
GhosttyTerminalOptions opts = {
.cols = 80,
.rows = 24,
.max_scrollback = 0,
};
if (ghostty_terminal_new(NULL, &terminal, opts) != GHOSTTY_SUCCESS) {
fprintf(stderr, "Failed to create terminal\n");
return 1;
}
/* Set cell pixel dimensions so kitty graphics can compute grid sizes. */
ghostty_terminal_resize(terminal, 80, 24, 8, 16);
/* Set a storage limit to enable Kitty graphics. */
uint64_t storage_limit = 64 * 1024 * 1024; /* 64 MiB */
ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT,
&storage_limit);
/* Install write_pty to see the protocol response. */
ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_WRITE_PTY,
(const void*)on_write_pty);
/*
* Send a Kitty graphics command with an inline 1x1 PNG image.
*
* The escape sequence is:
* ESC _G a=T,f=100,q=1; <base64 PNG data> ESC \
*
* Where:
* a=T — transmit and display
* f=100 — PNG format
* q=1 — request a response (q=0 would suppress it)
*/
printf("Sending Kitty graphics PNG image:\n");
const char* kitty_cmd =
"\x1b_Ga=T,f=100,q=1;"
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAA"
"DUlEQVR4nGP4z8DwHwAFAAH/iZk9HQAAAABJRU5ErkJggg=="
"\x1b\\";
ghostty_terminal_vt_write(terminal, (const uint8_t*)kitty_cmd,
strlen(kitty_cmd));
printf("PNG decode calls: %d\n", decode_count);
/* Query the kitty graphics storage to verify the image was stored. */
GhosttyKittyGraphics graphics = NULL;
if (ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS,
&graphics) != GHOSTTY_SUCCESS || !graphics) {
fprintf(stderr, "Failed to get kitty graphics storage\n");
return 1;
}
printf("\nKitty graphics storage is available.\n");
/*
* The storage-wide generation changes on every image/placement
* mutation. Renderers can compare it against the value from the
* previous frame: if unchanged, placement iteration and image
* staleness checks can be skipped entirely.
*/
uint64_t generation = 0;
ghostty_kitty_graphics_get(graphics, GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION,
&generation);
printf("Storage generation: %llu\n", (unsigned long long)generation);
/* Iterate placements to find the image ID. */
GhosttyKittyGraphicsPlacementIterator iter = NULL;
if (ghostty_kitty_graphics_placement_iterator_new(NULL, &iter) != GHOSTTY_SUCCESS) {
fprintf(stderr, "Failed to create placement iterator\n");
return 1;
}
if (ghostty_kitty_graphics_get(graphics,
GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR, &iter) != GHOSTTY_SUCCESS) {
fprintf(stderr, "Failed to get placement iterator\n");
return 1;
}
int placement_count = 0;
while (ghostty_kitty_graphics_placement_next(iter)) {
placement_count++;
uint32_t image_id = 0;
uint32_t placement_id = 0;
bool is_virtual = false;
int32_t z = 0;
ghostty_kitty_graphics_placement_get_multi(iter, 4,
(GhosttyKittyGraphicsPlacementData[]){
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID,
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_PLACEMENT_ID,
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IS_VIRTUAL,
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z,
},
(void*[]){ &image_id, &placement_id, &is_virtual, &z },
NULL);
printf(" placement #%d: image_id=%u placement_id=%u virtual=%s z=%d\n",
placement_count, image_id, placement_id,
is_virtual ? "true" : "false", z);
/* Look up the image and print its properties. */
GhosttyKittyGraphicsImage image =
ghostty_kitty_graphics_image(graphics, image_id);
if (!image) {
fprintf(stderr, "Failed to look up image %u\n", image_id);
return 1;
}
uint32_t width = 0, height = 0, number = 0;
GhosttyKittyImageFormat format = 0;
size_t data_len = 0;
uint64_t image_generation = 0;
/*
* The per-image generation changes on every add/replace of this
* image ID, so it detects retransmissions even when the size and
* format are unchanged. Texture caches should key staleness on it.
*/
ghostty_kitty_graphics_image_get_multi(image, 6,
(GhosttyKittyGraphicsImageData[]){
GHOSTTY_KITTY_IMAGE_DATA_NUMBER,
GHOSTTY_KITTY_IMAGE_DATA_WIDTH,
GHOSTTY_KITTY_IMAGE_DATA_HEIGHT,
GHOSTTY_KITTY_IMAGE_DATA_FORMAT,

```

--------------------------------

### Initialize GhosttyAllocator

Source: https://libghostty.tip.ghostty.org/structGhosttyAllocator.html

Example of initializing a GhosttyAllocator instance with a custom vtable and context.

```c
GhosttyAllocator allocator = {
.vtable = &my_allocator_vtable,
.ctx = my_allocator_state
};
```

--------------------------------

### Basic SGR Parsing Example

Source: https://libghostty.tip.ghostty.org/group__sgr.html

Demonstrates the lifecycle of an SGR parser, including initialization, parameter setting, attribute iteration, and cleanup.

```c
void basic_example() {
// Create parser
GhosttySgrParser parser;
GhosttyResult result = ghostty_sgr_new(NULL, &parser);
assert(result == GHOSTTY_SUCCESS);
// Parse "bold, red foreground" sequence: ESC[1;31m
uint16_t params[] = {1, 31};
result = ghostty_sgr_set_params(parser, params, NULL, 2);
assert(result == GHOSTTY_SUCCESS);
// Iterate through attributes
GhosttySgrAttribute attr;
while (ghostty_sgr_next(parser, &attr)) {
switch (attr.tag) {
case GHOSTTY_SGR_ATTR_BOLD:
printf("Bold enabled\n");
break;
case GHOSTTY_SGR_ATTR_FG_8:
printf("Foreground color: %d\n", attr.value.fg_8);
break;
default:
break;
}
}
// Cleanup
ghostty_sgr_free(parser);
}
```

--------------------------------

### Tracking a Grid Reference

Source: https://libghostty.tip.ghostty.org/c-vt-grid-ref-tracked_2src_2main_8c-example.html

This example initializes a terminal, tracks a specific coordinate, and demonstrates how the reference persists through scrolling and handles invalidation after a terminal reset.

```c
#include <assert.h>
#include <stdbool.h>
#include <stdio.h>
#include <string.h>
#include <ghostty/vt.h>
static uint32_t codepoint_at_tracked_ref(GhosttyTrackedGridRef tracked) {
GhosttyGridRef snapshot = GHOSTTY_INIT_SIZED(GhosttyGridRef);
GhosttyResult result = ghostty_tracked_grid_ref_snapshot(tracked, &snapshot);
assert(result == GHOSTTY_SUCCESS);
GhosttyCell cell;
result = ghostty_grid_ref_cell(&snapshot, &cell);
assert(result == GHOSTTY_SUCCESS);
bool has_text = false;
ghostty_cell_get(cell, GHOSTTY_CELL_DATA_HAS_TEXT, &has_text);
assert(has_text);
uint32_t codepoint = 0;
ghostty_cell_get(cell, GHOSTTY_CELL_DATA_CODEPOINT, &codepoint);
return codepoint;
}
int main() {
GhosttyTerminal terminal;
GhosttyTerminalOptions opts = {
.cols = 8,
.rows = 3,
.max_scrollback = 100,
};
GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
assert(result == GHOSTTY_SUCCESS);
const char *text = "alpha\r\n"
"bravo\r\n"
"charlie";
ghostty_terminal_vt_write(
terminal, (const uint8_t *)text, strlen(text));
GhosttyTrackedGridRef tracked = NULL;
GhosttyPoint alpha = {
.tag = GHOSTTY_POINT_TAG_ACTIVE,
.value = { .coordinate = { .x = 0, .y = 0 } },
};
result = ghostty_terminal_grid_ref_track(terminal, alpha, &tracked);
assert(result == GHOSTTY_SUCCESS);
// Writing another line scrolls the original "alpha" row into scrollback.
// The tracked ref still follows the same cell.
const char *more = "\r\ndelta";
ghostty_terminal_vt_write(
terminal, (const uint8_t *)more, strlen(more));
assert(ghostty_tracked_grid_ref_has_value(tracked));
printf("tracked codepoint after scroll: %c\n",
(char)codepoint_at_tracked_ref(tracked));
GhosttyPointCoordinate screen = {0};
result = ghostty_tracked_grid_ref_point(
tracked, GHOSTTY_POINT_TAG_SCREEN, &screen);
assert(result == GHOSTTY_SUCCESS);
printf("tracked screen point: %u,%u\n", screen.x, screen.y);
// Resetting the terminal discards the old grid contents. The tracked
// handle remains valid, but no longer has a meaningful location.
ghostty_terminal_reset(terminal);
assert(!ghostty_tracked_grid_ref_has_value(tracked));
GhosttyGridRef discarded = GHOSTTY_INIT_SIZED(GhosttyGridRef);
result = ghostty_tracked_grid_ref_snapshot(tracked, &discarded);
assert(result == GHOSTTY_NO_VALUE);
// The same handle can be moved to a new point after it loses its value.
const char *replacement = "echo";
ghostty_terminal_vt_write(
terminal, (const uint8_t *)replacement, strlen(replacement));
GhosttyPoint echo = {
.tag = GHOSTTY_POINT_TAG_ACTIVE,
.value = { .coordinate = { .x = 0, .y = 0 } },
};
result = ghostty_tracked_grid_ref_set(tracked, terminal, echo);
assert(result == GHOSTTY_SUCCESS);
assert(ghostty_tracked_grid_ref_has_value(tracked));
printf("tracked codepoint after reset/set: %c\n",
(char)codepoint_at_tracked_ref(tracked));
ghostty_tracked_grid_ref_free(tracked);
ghostty_terminal_free(terminal);
return 0;
}
```

--------------------------------

### Ghostty Selection Gesture Implementation

Source: https://libghostty.tip.ghostty.org/group__selection.html

A complete example demonstrating the lifecycle of selection gestures, including event creation, state updates, and selection formatting.

```c
.value = { .coordinate = { .x = x, .y = y } },
};
GhosttyResult result = ghostty_terminal_grid_ref(terminal, point, &ref);
assert(result == GHOSTTY_SUCCESS);
return ref;
}
static void print_selection(
GhosttyTerminal terminal,
const char *label,
const GhosttySelection *selection) {
GhosttyTerminalSelectionFormatOptions opts =
GHOSTTY_INIT_SIZED(GhosttyTerminalSelectionFormatOptions);
opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
opts.trim = true;
opts.selection = selection;
uint8_t *buf = NULL;
size_t len = 0;
GhosttyResult result = ghostty_terminal_selection_format_alloc(
terminal, NULL, opts, &buf, &len);
assert(result == GHOSTTY_SUCCESS);
printf("%s: ", label);
fwrite(buf, 1, len, stdout);
printf("\n");
ghostty_free(NULL, buf, len);
}
static GhosttySelectionGestureEvent new_event(
GhosttySelectionGestureEventType type) {
GhosttySelectionGestureEvent event = NULL;
GhosttyResult result = ghostty_selection_gesture_event_new(NULL, &event, type);
assert(result == GHOSTTY_SUCCESS);
return event;
}
int main() {
GhosttyTerminal terminal;
GhosttyTerminalOptions opts = {
.cols = 20,
.rows = 4,
.max_scrollback = 100,
};
GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
assert(result == GHOSTTY_SUCCESS);
vt_write(terminal, "hello world\r\nsecond line");
GhosttySelectionGesture gesture = NULL;
result = ghostty_selection_gesture_new(NULL, &gesture);
assert(result == GHOSTTY_SUCCESS);
GhosttySelectionGestureEvent press =
new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS);
GhosttySelectionGestureEvent drag =
new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG);
GhosttySelectionGestureEvent release =
new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE);
GhosttySelectionGestureEvent deep_press =
new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS);
GhosttySelectionGestureGeometry geometry = {
.columns = 20,
.cell_width = 10,
.padding_left = 0,
.screen_height = 40,
};
// Press in the first cell. A normal single press records the click anchor but
// doesn't produce a selection yet, so we discard the optional output.
GhosttyGridRef press_ref = ref_at(terminal, 0, 0);
result = ghostty_selection_gesture_event_set(
press, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF, &press_ref);
assert(result == GHOSTTY_SUCCESS);
GhosttySurfacePosition press_pos = { .x = 2, .y = 8 };
result = ghostty_selection_gesture_event_set(
press, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION, &press_pos);
assert(result == GHOSTTY_SUCCESS);
result = ghostty_selection_gesture_event(
gesture, terminal, press, NULL);
assert(result == GHOSTTY_NO_VALUE);
// Drag across "hello". The drag event returns a selection snapshot that the
// embedder can apply to its UI, copy, or format immediately.
GhosttyGridRef drag_ref = ref_at(terminal, 4, 0);
result = ghostty_selection_gesture_event_set(
drag, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF, &drag_ref);
assert(result == GHOSTTY_SUCCESS);
GhosttySurfacePosition drag_pos = { .x = 46, .y = 8 };
result = ghostty_selection_gesture_event_set(
drag, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION, &drag_pos);
assert(result == GHOSTTY_SUCCESS);
result = ghostty_selection_gesture_event_set(
drag, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY, &geometry);
assert(result == GHOSTTY_SUCCESS);
GhosttySelection selection = GHOSTTY_INIT_SIZED(GhosttySelection);
result = ghostty_selection_gesture_event(
gesture, terminal, drag, &selection);
assert(result == GHOSTTY_SUCCESS);
print_selection(terminal, "drag", &selection);
// Release updates gesture state but never produces a selection.
result = ghostty_selection_gesture_event_set(
release, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF, &drag_ref);
assert(result == GHOSTTY_SUCCESS);
result = ghostty_selection_gesture_event(
gesture, terminal, release, NULL);
assert(result == GHOSTTY_NO_VALUE);
bool dragged = false;
result = ghostty_selection_gesture_get(
gesture, terminal, GHOSTTY_SELECTION_GESTURE_DATA_DRAGGED, &dragged);
assert(result == GHOSTTY_SUCCESS);
printf("dragged: %s\n", dragged ? "true" : "false");
// Deep press uses the active click anchor to select the surrounding word.
ghostty_selection_gesture_reset(gesture, terminal);
GhosttyGridRef world_ref = ref_at(terminal, 6, 0);
result = ghostty_selection_gesture_event_set(
press, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF, &world_ref);
assert(result == GHOSTTY_SUCCESS);
result = ghostty_selection_gesture_event(
gesture, terminal, press, NULL);
assert(result == GHOSTTY_NO_VALUE);
result = ghostty_selection_gesture_event(
gesture, terminal, deep_press, &selection);
assert(result == GHOSTTY_SUCCESS);
print_selection(terminal, "deep press", &selection);
ghostty_selection_gesture_event_free(deep_press);
ghostty_selection_gesture_event_free(release);
ghostty_selection_gesture_event_free(drag);
ghostty_selection_gesture_event_free(press);
ghostty_selection_gesture_free(gesture, terminal);
ghostty_terminal_free(terminal);
return 0;
}
```

--------------------------------

### Traverse Terminal Grid with Grid Refs

Source: https://libghostty.tip.ghostty.org/c-vt-grid-traverse_2src_2main_8c-example.html

This example shows how to iterate over terminal rows and columns to inspect cell codepoints, row wrap status, and bold styling.

```c
#include <assert.h>
#include <stdio.h>
#include <string.h>
#include <ghostty/vt.h>
int main() {
// Create a small terminal
GhosttyTerminal terminal;
GhosttyTerminalOptions opts = {
.cols = 10,
.rows = 3,
.max_scrollback = 0,
};
GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
assert(result == GHOSTTY_SUCCESS);
// Write some content so the grid has interesting data
const char *text = "Hello!\r\n" // Row 0: H e l l o !
"World\r\n" // Row 1: W o r l d
"\033[1mBold"; // Row 2: B o l d (bold style)
ghostty_terminal_vt_write(
terminal, (const uint8_t *)text, strlen(text));
// Get terminal dimensions
uint16_t cols, rows;
ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_COLS, &cols);
ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_ROWS, &rows);
// Traverse the entire grid using grid refs
for (uint16_t row = 0; row < rows; row++) {
printf("Row %u: ", row);
for (uint16_t col = 0; col < cols; col++) {
// Resolve the point to a grid reference
GhosttyGridRef ref = GHOSTTY_INIT_SIZED(GhosttyGridRef);
GhosttyPoint pt = {
.tag = GHOSTTY_POINT_TAG_ACTIVE,
.value = { .coordinate = { .x = col, .y = row } },
};
result = ghostty_terminal_grid_ref(terminal, pt, &ref);
assert(result == GHOSTTY_SUCCESS);
// Read the cell from the grid ref
GhosttyCell cell;
result = ghostty_grid_ref_cell(&ref, &cell);
assert(result == GHOSTTY_SUCCESS);
// Check if the cell has text
bool has_text = false;
ghostty_cell_get(cell, GHOSTTY_CELL_DATA_HAS_TEXT, &has_text);
if (has_text) {
uint32_t codepoint = 0;
ghostty_cell_get(cell, GHOSTTY_CELL_DATA_CODEPOINT, &codepoint);
printf("%c", (char)codepoint);
} else {
printf(".");
}
}
// Also inspect the row for wrap state
GhosttyGridRef ref = GHOSTTY_INIT_SIZED(GhosttyGridRef);
GhosttyPoint pt = {
.tag = GHOSTTY_POINT_TAG_ACTIVE,
.value = { .coordinate = { .x = 0, .y = row } },
};
ghostty_terminal_grid_ref(terminal, pt, &ref);
GhosttyRow grid_row;
ghostty_grid_ref_row(&ref, &grid_row);
bool wrap = false;
ghostty_row_get(grid_row, GHOSTTY_ROW_DATA_WRAP, &wrap);
printf(" (wrap=%s", wrap ? "true" : "false");
// Check the style of the first cell with text
GhosttyStyle style = GHOSTTY_INIT_SIZED(GhosttyStyle);
ghostty_grid_ref_style(&ref, &style);
printf(", bold=%s)\n", style.bold ? "true" : "false");
}
ghostty_terminal_free(terminal);
return 0;
}
```

--------------------------------

### ghostty_terminal_select_output()

Source: https://libghostty.tip.ghostty.org/group__selection.html

Derive a command-output selection snapshot from a terminal grid reference. The returned selection is a snapshot and is not installed as the terminal's current selection.

```APIDOC
## ghostty_terminal_select_output()

### Description
Derive a command-output selection snapshot from a terminal grid reference. The returned selection is not installed as the terminal's current selection.

### Signature
GhosttyResult ghostty_terminal_select_output(GhosttyTerminal terminal, GhosttyGridRef ref, GhosttySelection *out_selection)

### Parameters
- **terminal** (GhosttyTerminal) - The terminal handle.
- **ref** (GhosttyGridRef) - Grid reference within command output to select.
- **out_selection** (GhosttySelection *) - On success, receives the derived selection.

### Returns
- **GHOSTTY_SUCCESS** on success.
- **GHOSTTY_NO_VALUE** if the valid ref is not selectable command output.
- **GHOSTTY_INVALID_VALUE** if the terminal, ref, or output pointer is invalid.
```

--------------------------------

### ghostty_terminal_mode_get

Source: https://libghostty.tip.ghostty.org/terminal_8h.html

Gets the state of a terminal mode.

```APIDOC
## ghostty_terminal_mode_get

### Signature
`GhosttyResult ghostty_terminal_mode_get(GhosttyTerminal terminal, GhosttyMode mode, bool *out_value)`
```

--------------------------------

### Querying Build Configuration and Version Information

Source: https://libghostty.tip.ghostty.org/c-vt-build-info_2src_2main_8c-example.html

Demonstrates how to retrieve SIMD, graphics, and control mode support, as well as detailed version strings and components.

```c
#include <stdio.h>
#include <ghostty/vt.h>
void query_build_info() {
bool simd = false;
bool kitty_graphics = false;
bool tmux_control_mode = false;
ghostty_build_info(GHOSTTY_BUILD_INFO_SIMD, &simd);
ghostty_build_info(GHOSTTY_BUILD_INFO_KITTY_GRAPHICS, &kitty_graphics);
ghostty_build_info(GHOSTTY_BUILD_INFO_TMUX_CONTROL_MODE, &tmux_control_mode);
printf("SIMD: %s\n", simd ? "enabled" : "disabled");
printf("Kitty graphics: %s\n", kitty_graphics ? "enabled" : "disabled");
printf("Tmux control mode: %s\n", tmux_control_mode ? "enabled" : "disabled");
GhosttyString version_string = {0};
size_t version_major = 0;
size_t version_minor = 0;
size_t version_patch = 0;
GhosttyString version_pre = {0};
GhosttyString version_build = {0};
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_STRING, &version_string);
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_MAJOR, &version_major);
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_MINOR, &version_minor);
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_PATCH, &version_patch);
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_PRE, &version_pre);
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_BUILD, &version_build);
printf("Version: %.*s\n", (int)version_string.len, version_string.ptr);
printf("Version major: %zu\n", version_major);
printf("Version minor: %zu\n", version_minor);
printf("Version patch: %zu\n", version_patch);
if (version_pre.len > 0) {
printf("Version pre : %.*s\n", (int)version_pre.len, version_pre.ptr);
} else {
printf("Version pre : (none)\n");
}
if (version_build.len > 0) {
printf("Version build: %.*s\n", (int)version_build.len, version_build.ptr);
} else {
printf("Version build: (none)\n");
}
}
int main() {
query_build_info();
return 0;
}
```

--------------------------------

### Get selection order

Source: https://libghostty.tip.ghostty.org/selection_8h_source.html

Retrieves the current ordering of a selection.

```c
GHOSTTY_API GhosttyResult ghostty_terminal_selection_order(GhosttyTerminal terminal, const GhosttySelection *selection, GhosttySelectionOrder *out_order)
```

--------------------------------

### Initialize and Inspect Kitty Graphics

Source: https://libghostty.tip.ghostty.org/group__kitty__graphics.html

Demonstrates setting up a terminal with Kitty graphics support, sending an image, and iterating through placements to retrieve metadata.

```c
int main() {
/* Install the PNG decoder via the sys interface. */
int decode_count = 0;
ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, &decode_count);
ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, (const void*)decode_png);
/* Create a terminal with Kitty graphics enabled. */
GhosttyTerminal terminal = NULL;
GhosttyTerminalOptions opts = {
.cols = 80,
.rows = 24,
.max_scrollback = 0,
};
if (ghostty_terminal_new(NULL, &terminal, opts) != GHOSTTY_SUCCESS) {
fprintf(stderr, "Failed to create terminal\n");
return 1;
}
/* Set cell pixel dimensions so kitty graphics can compute grid sizes. */
ghostty_terminal_resize(terminal, 80, 24, 8, 16);
/* Set a storage limit to enable Kitty graphics. */
uint64_t storage_limit = 64 * 1024 * 1024; /* 64 MiB */
ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT,
&storage_limit);
/* Install write_pty to see the protocol response. */
ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_WRITE_PTY,
(const void*)on_write_pty);
/*
* Send a Kitty graphics command with an inline 1x1 PNG image.
*
* The escape sequence is:
* ESC _G a=T,f=100,q=1; <base64 PNG data> ESC \
*
* Where:
* a=T — transmit and display
* f=100 — PNG format
* q=1 — request a response (q=0 would suppress it)
*/
printf("Sending Kitty graphics PNG image:\n");
const char* kitty_cmd =
"\x1b_Ga=T,f=100,q=1;"
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAA"
"DUlEQVR4nGP4z8DwHwAFAAH/iZk9HQAAAABJRU5ErkJggg=="
"\x1b\\";
ghostty_terminal_vt_write(terminal, (const uint8_t*)kitty_cmd,
strlen(kitty_cmd));
printf("PNG decode calls: %d\n", decode_count);
/* Query the kitty graphics storage to verify the image was stored. */
GhosttyKittyGraphics graphics = NULL;
if (ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS,
&graphics) != GHOSTTY_SUCCESS || !graphics) {
fprintf(stderr, "Failed to get kitty graphics storage\n");
return 1;
}
printf("\nKitty graphics storage is available.\n");
/*
* The storage-wide generation changes on every image/placement
* mutation. Renderers can compare it against the value from the
* previous frame: if unchanged, placement iteration and image
* staleness checks can be skipped entirely.
*/
uint64_t generation = 0;
ghostty_kitty_graphics_get(graphics, GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION,
&generation);
printf("Storage generation: %llu\n", (unsigned long long)generation);
/* Iterate placements to find the image ID. */
GhosttyKittyGraphicsPlacementIterator iter = NULL;
if (ghostty_kitty_graphics_placement_iterator_new(NULL, &iter) != GHOSTTY_SUCCESS) {
fprintf(stderr, "Failed to create placement iterator\n");
return 1;
}
if (ghostty_kitty_graphics_get(graphics,
GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR, &iter) != GHOSTTY_SUCCESS) {
fprintf(stderr, "Failed to get placement iterator\n");
return 1;
}
int placement_count = 0;
while (ghostty_kitty_graphics_placement_next(iter)) {
placement_count++;
uint32_t image_id = 0;
uint32_t placement_id = 0;
bool is_virtual = false;
int32_t z = 0;
ghostty_kitty_graphics_placement_get_multi(iter, 4,
(GhosttyKittyGraphicsPlacementData[]){
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID,
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_PLACEMENT_ID,
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IS_VIRTUAL,
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z,
},
(void*[]){ &image_id, &placement_id, &is_virtual, &z },
NULL);
printf(" placement #%d: image_id=%u placement_id=%u virtual=%s z=%d\n",
placement_count, image_id, placement_id,
is_virtual ? "true" : "false", z);
/* Look up the image and print its properties. */
```

--------------------------------

### ghostty_terminal_selection_order

Source: https://libghostty.tip.ghostty.org/group__selection.html

Get the current endpoint ordering of a selection snapshot.

```APIDOC
## ghostty_terminal_selection_order

### Description
Get the current endpoint ordering of a selection snapshot. The selection's start and end grid refs must both be valid untracked snapshots for the given terminal's currently active screen.

### Signature
GhosttyResult ghostty_terminal_selection_order(GhosttyTerminal terminal, const GhosttySelection *selection, GhosttySelectionOrder *out_order)

### Parameters
- **terminal** (GhosttyTerminal) - The terminal handle (NULL returns GHOSTTY_INVALID_VALUE).
- **selection** (const GhosttySelection *) - Selection snapshot to inspect.
- **out_order** (GhosttySelectionOrder *) - On success, receives the selection order.

### Returns
GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal, selection, or output pointer are invalid.
```

--------------------------------

### Get gesture data

Source: https://libghostty.tip.ghostty.org/selection_8h_source.html

Retrieves specific data from a selection gesture.

```c
GHOSTTY_API GhosttyResult ghostty_selection_gesture_get(GhosttySelectionGesture gesture, GhosttyTerminal terminal, GhosttySelectionGestureData data, void *value)
```

--------------------------------

### Querying Build Configuration and Version Info

Source: https://libghostty.tip.ghostty.org/group__build__info.html

Demonstrates how to retrieve various build-time flags and version components using ghostty_build_info.

```c
void query_build_info() {
bool simd = false;
bool kitty_graphics = false;
bool tmux_control_mode = false;
ghostty_build_info(GHOSTTY_BUILD_INFO_SIMD, &simd);
ghostty_build_info(GHOSTTY_BUILD_INFO_KITTY_GRAPHICS, &kitty_graphics);
ghostty_build_info(GHOSTTY_BUILD_INFO_TMUX_CONTROL_MODE, &tmux_control_mode);
printf("SIMD: %s\n", simd ? "enabled" : "disabled");
printf("Kitty graphics: %s\n", kitty_graphics ? "enabled" : "disabled");
printf("Tmux control mode: %s\n", tmux_control_mode ? "enabled" : "disabled");
GhosttyString version_string = {0};
size_t version_major = 0;
size_t version_minor = 0;
size_t version_patch = 0;
GhosttyString version_pre = {0};
GhosttyString version_build = {0};
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_STRING, &version_string);
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_MAJOR, &version_major);
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_MINOR, &version_minor);
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_PATCH, &version_patch);
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_PRE, &version_pre);
ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_BUILD, &version_build);
printf("Version: %.*s\n", (int)version_string.len, version_string.ptr);
printf("Version major: %zu\n", version_major);
printf("Version minor: %zu\n", version_minor);
printf("Version patch: %zu\n", version_patch);
if (version_pre.len > 0) {
printf("Version pre : %.*s\n", (int)version_pre.len, version_pre.ptr);
} else {
printf("Version pre : (none)\n");
}
if (version_build.len > 0) {
printf("Version build: %.*s\n", (int)version_build.len, version_build.ptr);
} else {
printf("Version build: (none)\n");
}
}
```

--------------------------------

### Get cell data

Source: https://libghostty.tip.ghostty.org/c-vt-grid-ref-tracked_2src_2main_8c-example.html

Retrieves data from a specific terminal cell.

```c
GHOSTTY_API GhosttyResult ghostty_cell_get(GhosttyCell cell, GhosttyCellData data, void *out)
```

--------------------------------

### Initialize and Use GhosttyColorPaletteMask

Source: https://libghostty.tip.ghostty.org/structGhosttyColorPaletteMask.html

Demonstrates initializing a mask, setting a bit, and checking if a specific index is set.

```c
GhosttyColorPaletteMask mask = {0};
GHOSTTY_COLOR_PALETTE_MASK_SET(&mask, 20);
if (GHOSTTY_COLOR_PALETTE_MASK_IS_SET(&mask, 20)) {
// Index 20 will be preserved.
}
```

--------------------------------

### Get multiple gesture data values

Source: https://libghostty.tip.ghostty.org/selection_8h_source.html

Retrieves multiple data values from a selection gesture.

```c
GHOSTTY_API GhosttyResult ghostty_selection_gesture_get_multi(GhosttySelectionGesture gesture, GhosttyTerminal terminal, size_t count, const GhosttySelectionGestureData *keys, void **values, size_t *out_written)
```

--------------------------------

### Manage terminal lifecycle and OSC overrides in C

Source: https://libghostty.tip.ghostty.org/group__terminal.html

Demonstrates creating a terminal instance, setting defaults, applying OSC color overrides, and clearing defaults.

```c
int main() {
// Create a terminal
GhosttyTerminal terminal = NULL;
GhosttyTerminalOptions opts = {
.cols = 80,
.rows = 24,
.max_scrollback = 0,
};
if (ghostty_terminal_new(NULL, &terminal, opts) != GHOSTTY_SUCCESS) {
fprintf(stderr, "Failed to create terminal\n");
return 1;
}
// Before setting any colors, everything is unset
print_all_colors(terminal, "Before setting defaults");
// Set our color theme defaults
set_color_theme(terminal);
print_all_colors(terminal, "\nAfter setting defaults");
// Simulate an OSC override (e.g. a program running inside the
// terminal changes the foreground via OSC 10)
const char* osc_fg = "\x1B]10;rgb:FF/00/00\x1B\\";
ghostty_terminal_vt_write(terminal, (const uint8_t*)osc_fg,
strlen(osc_fg));
print_all_colors(terminal, "\nAfter OSC foreground override");
// Clear the foreground default — the OSC override is still active
ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND, NULL);
print_all_colors(terminal, "\nAfter clearing foreground default");
ghostty_terminal_free(terminal);
return 0;
}
```

--------------------------------

### Graphics Placement and System Cleanup

Source: https://libghostty.tip.ghostty.org/group__sys.html

Demonstrates iterating through graphics placements, calculating pixel and grid sizes, and resetting system callbacks.

```c
GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN,
GHOSTTY_KITTY_IMAGE_DATA_GENERATION,
},
(void*[]){ &number, &width, &height, &format, &data_len,
&image_generation },
NULL);
printf(" image: number=%u size=%ux%u format=%d data_len=%zu "
"generation=%llu\n",
number, width, height, format, data_len,
(unsigned long long)image_generation);
/* Compute the rendered pixel size and grid size. */
uint32_t px_w = 0, px_h = 0, cols = 0, rows = 0;
if (ghostty_kitty_graphics_placement_pixel_size(iter, image, terminal,
&px_w, &px_h) == GHOSTTY_SUCCESS) {
printf(" rendered pixel size: %ux%u\n", px_w, px_h);
}
if (ghostty_kitty_graphics_placement_grid_size(iter, image, terminal,
&cols, &rows) == GHOSTTY_SUCCESS) {
printf(" grid size: %u cols x %u rows\n", cols, rows);
}
}
printf("Total placements: %d\n", placement_count);
ghostty_kitty_graphics_placement_iterator_free(iter);
/* Clean up. */
ghostty_terminal_free(terminal);
/* Clear the sys callbacks. */
ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, NULL);
ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, NULL);
return 0;
}
```

--------------------------------

### Get storage word for palette index

Source: https://libghostty.tip.ghostty.org/group__color.html

Calculates the storage word index for a given palette index (0-255).

```c
#define GHOSTTY_COLOR_PALETTE_MASK_WORD(index) ((index) >> 6)
```

--------------------------------

### Initialize a terminal

Source: https://libghostty.tip.ghostty.org/c-vt-grid-ref-tracked_2src_2main_8c-example.html

Creates a new terminal instance with the provided allocator and options.

```c
GHOSTTY_API GhosttyResult ghostty_terminal_new(const GhosttyAllocator *allocator, GhosttyTerminal *terminal, GhosttyTerminalOptions options)
```

--------------------------------

### Key Event Accessors

Source: https://libghostty.tip.ghostty.org/key_2event_8h.html

Methods to get and set properties of a GhosttyKeyEvent, such as action, key, modifiers, and UTF-8 content.

```APIDOC
## Key Event Accessors

### Description
Functions to manipulate the state of a key event.

### Methods
- void ghostty_key_event_set_action(GhosttyKeyEvent *event, GhosttyKeyAction action);
- GhosttyKeyAction ghostty_key_event_get_action(const GhosttyKeyEvent *event);
- void ghostty_key_event_set_key(GhosttyKeyEvent *event, GhosttyKey key);
- GhosttyKey ghostty_key_event_get_key(const GhosttyKeyEvent *event);
- void ghostty_key_event_set_mods(GhosttyKeyEvent *event, GhosttyMods mods);
- GhosttyMods ghostty_key_event_get_mods(const GhosttyKeyEvent *event);
- void ghostty_key_event_set_utf8(GhosttyKeyEvent *event, const char *utf8);
- const char *ghostty_key_event_get_utf8(const GhosttyKeyEvent *event);
```

--------------------------------

### ghostty_sys_set

Source: https://libghostty.tip.ghostty.org/group__sys.html

Installs or clears a system implementation for a specific option. Passing NULL as the value disables the corresponding feature.

```APIDOC
## ghostty_sys_set

### Description
Installs or clears a system implementation for a specific option. This must be configured at startup before terminal functionality that depends on the implementation is used.

### Parameters
- **option** (GhosttySysOption) - Required - The system option to configure.
- **value** (void*) - Required - The function pointer implementation to install, or NULL to clear the implementation and disable the feature.
```

--------------------------------

### Handling Selection Gestures

Source: https://libghostty.tip.ghostty.org/c-vt-selection-gesture_2src_2main_8c-example.html

Demonstrates the lifecycle of selection gestures including event creation, coordinate mapping, and snapshot retrieval.

```c
#include <assert.h>
#include <stdbool.h>
#include <stdio.h>
#include <string.h>
#include <ghostty/vt.h>
static void vt_write(GhosttyTerminal terminal, const char *s) {
ghostty_terminal_vt_write(terminal, (const uint8_t *)s, strlen(s));
}
static GhosttyGridRef ref_at(GhosttyTerminal terminal, uint16_t x, uint16_t y) {
GhosttyGridRef ref = GHOSTTY_INIT_SIZED(GhosttyGridRef);
GhosttyPoint point = {
.tag = GHOSTTY_POINT_TAG_ACTIVE,
.value = { .coordinate = { .x = x, .y = y } },
};
GhosttyResult result = ghostty_terminal_grid_ref(terminal, point, &ref);
assert(result == GHOSTTY_SUCCESS);
return ref;
}
static void print_selection(
GhosttyTerminal terminal,
const char *label,
const GhosttySelection *selection) {
GhosttyTerminalSelectionFormatOptions opts =
GHOSTTY_INIT_SIZED(GhosttyTerminalSelectionFormatOptions);
opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
opts.trim = true;
opts.selection = selection;
uint8_t *buf = NULL;
size_t len = 0;
GhosttyResult result = ghostty_terminal_selection_format_alloc(
terminal, NULL, opts, &buf, &len);
assert(result == GHOSTTY_SUCCESS);
printf("%s: ", label);
fwrite(buf, 1, len, stdout);
printf("\n");
ghostty_free(NULL, buf, len);
}
static GhosttySelectionGestureEvent new_event(
GhosttySelectionGestureEventType type) {
GhosttySelectionGestureEvent event = NULL;
GhosttyResult result = ghostty_selection_gesture_event_new(NULL, &event, type);
assert(result == GHOSTTY_SUCCESS);
return event;
}
int main() {
GhosttyTerminal terminal;
GhosttyTerminalOptions opts = {
.cols = 20,
.rows = 4,
.max_scrollback = 100,
};
GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
assert(result == GHOSTTY_SUCCESS);
vt_write(terminal, "hello world\r\nsecond line");
GhosttySelectionGesture gesture = NULL;
result = ghostty_selection_gesture_new(NULL, &gesture);
assert(result == GHOSTTY_SUCCESS);
GhosttySelectionGestureEvent press =
new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS);
GhosttySelectionGestureEvent drag =
new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG);
GhosttySelectionGestureEvent release =
new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE);
GhosttySelectionGestureEvent deep_press =
new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS);
GhosttySelectionGestureGeometry geometry = {
.columns = 20,
.cell_width = 10,
.padding_left = 0,
.screen_height = 40,
};
// Press in the first cell. A normal single press records the click anchor but
// doesn't produce a selection yet, so we discard the optional output.
GhosttyGridRef press_ref = ref_at(terminal, 0, 0);
result = ghostty_selection_gesture_event_set(
press, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF, &press_ref);
assert(result == GHOSTTY_SUCCESS);
GhosttySurfacePosition press_pos = { .x = 2, .y = 8 };
result = ghostty_selection_gesture_event_set(
press, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION, &press_pos);
assert(result == GHOSTTY_SUCCESS);
result = ghostty_selection_gesture_event(
gesture, terminal, press, NULL);
assert(result == GHOSTTY_NO_VALUE);
// Drag across "hello". The drag event returns a selection snapshot that the
// embedder can apply to its UI, copy, or format immediately.
GhosttyGridRef drag_ref = ref_at(terminal, 4, 0);
result = ghostty_selection_gesture_event_set(
drag, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF, &drag_ref);
assert(result == GHOSTTY_SUCCESS);
GhosttySurfacePosition drag_pos = { .x = 46, .y = 8 };
result = ghostty_selection_gesture_event_set(
drag, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION, &drag_pos);
assert(result == GHOSTTY_SUCCESS);
result = ghostty_selection_gesture_event_set(
drag, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY, &geometry);
assert(result == GHOSTTY_SUCCESS);
GhosttySelection selection = GHOSTTY_INIT_SIZED(GhosttySelection);
result = ghostty_selection_gesture_event(
gesture, terminal, drag, &selection);
assert(result == GHOSTTY_SUCCESS);
print_selection(terminal, "drag", &selection);
```

--------------------------------

### ghostty_terminal_select_word()

Source: https://libghostty.tip.ghostty.org/group__selection.html

Derive a word selection snapshot from a terminal grid reference. The returned selection is a snapshot and is not installed as the terminal's current selection.

```APIDOC
## ghostty_terminal_select_word()

### Description
Derive a word selection snapshot from a terminal grid reference. The returned selection is not installed as the terminal's current selection.

### Signature
GhosttyResult ghostty_terminal_select_word(GhosttyTerminal terminal, const GhosttyTerminalSelectWordOptions *options, GhosttySelection *out_selection)

### Parameters
- **terminal** (GhosttyTerminal) - The terminal handle.
- **options** (GhosttyTerminalSelectWordOptions *) - Word-selection options.
- **out_selection** (GhosttySelection *) - On success, receives the derived selection.

### Returns
- **GHOSTTY_SUCCESS** on success.
- **GHOSTTY_NO_VALUE** if the valid ref has no selectable word content.
- **GHOSTTY_INVALID_VALUE** if the terminal, options, ref, codepoint pointer, or output pointer are invalid.
```

--------------------------------

### Include build_info.h dependencies

Source: https://libghostty.tip.ghostty.org/build__info_8h.html

Required headers for using the build info interface.

```c
#include <stddef.h>
#include <stdbool.h>
#include <ghostty/vt/types.h>
```
Tokens:
Raw