Selection

Detailed Description

A snapshot selection range defined by two grid references that identifies a contiguous or rectangular region of terminal content.

The start and end values are GhosttyGridRef values. They are therefore untracked grid references and inherit the same lifetime rules: they are only safe to use until the next mutating operation on the terminal that produced them, including freeing the terminal. To keep a selection valid across terminal mutations, callers must maintain tracked grid references for the endpoints and reconstruct a GhosttySelection from fresh snapshots when needed.

Selection gestures provide a reusable state machine for turning UI pointer interactions into selection snapshots. A caller creates one GhosttySelectionGesture per active gesture stream, reuses typed GhosttySelectionGestureEvent objects for synthetic press, drag, release, autoscroll tick, and deep-press events, and applies each event with ghostty_selection_gesture_event(). The returned GhosttySelection is a snapshot; the embedder decides whether to render it, format/copy it, or install it as the terminal's active selection.

Examples

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) {
  GhosttyFormatterTerminalOptions opts = GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
  opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
  opts.trim = true;
  opts.selection = selection;
 
  GhosttyFormatter formatter;
  GhosttyResult result = ghostty_formatter_terminal_new(
      NULL, &formatter, terminal, opts);
  assert(result == GHOSTTY_SUCCESS);
 
  uint8_t *buf = NULL;
  size_t len = 0;
  result = ghostty_formatter_format_alloc(formatter, NULL, &buf, &len);
  assert(result == GHOSTTY_SUCCESS);
 
  printf("%s: ", label);
  fwrite(buf, 1, len, stdout);
  printf("\n");
 
  ghostty_free(NULL, buf, len);
  ghostty_formatter_free(formatter);
}
 
int main() {
  GhosttyTerminal terminal;
  GhosttyTerminalOptions opts = {
    .cols = 80,
    .rows = 8,
    .max_scrollback = 0,
  };
  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
  assert(result == GHOSTTY_SUCCESS);
 
  // A realistic shell transcript with OSC 133 semantic prompt markers.
  // Ghostty uses these markers to distinguish prompt/input from command
  // output for semantic line and output selections.
  vt_write(terminal,
      "\033]133;A\007$ "           // Prompt starts: "$ "
      "\033]133;B\007git status"  // Input starts: "git status"
      "\033]133;C\007\r\n"        // Output starts after Enter
      "On branch main\r\n"
      "nothing to commit, working tree clean");
 
  GhosttySelection selection = GHOSTTY_INIT_SIZED(GhosttySelection);
 
  // Double-click style word selection under the cursor.
  GhosttyTerminalSelectWordOptions word = GHOSTTY_INIT_SIZED(GhosttyTerminalSelectWordOptions);
  word.ref = ref_at(terminal, 6, 0); // the "status" in "git status"
  result = ghostty_terminal_select_word(terminal, &word, &selection);
  assert(result == GHOSTTY_SUCCESS);
  print_selection(terminal, "word", &selection);

  // Double-click-and-drag style selection. Suppose the user double-clicks
  // "git" and drags to "status". The pointer may pass over whitespace, so
  // select the nearest word between the original click and current drag point
  // in both directions, then combine the outer word bounds.
  GhosttyGridRef click_ref = ref_at(terminal, 2, 0); // the "git" in "git status"
  GhosttyGridRef drag_ref = ref_at(terminal, 6, 0);  // the "status" in "git status"
 
  GhosttyTerminalSelectWordBetweenOptions start_word_opts =
      GHOSTTY_INIT_SIZED(GhosttyTerminalSelectWordBetweenOptions);
  start_word_opts.start = click_ref;
  start_word_opts.end = drag_ref;
 
  GhosttySelection start_word = GHOSTTY_INIT_SIZED(GhosttySelection);
  result = ghostty_terminal_select_word_between(
      terminal, &start_word_opts, &start_word);
  assert(result == GHOSTTY_SUCCESS);
 
  GhosttyTerminalSelectWordBetweenOptions end_word_opts =
      GHOSTTY_INIT_SIZED(GhosttyTerminalSelectWordBetweenOptions);
  end_word_opts.start = drag_ref;
  end_word_opts.end = click_ref;
 
  GhosttySelection end_word = GHOSTTY_INIT_SIZED(GhosttySelection);
  result = ghostty_terminal_select_word_between(
      terminal, &end_word_opts, &end_word);
  assert(result == GHOSTTY_SUCCESS);
 
  GhosttySelection drag_selection = GHOSTTY_INIT_SIZED(GhosttySelection);
  drag_selection.start = start_word.start;
  drag_selection.end = end_word.end;
  print_selection(terminal, "double-click drag", &drag_selection);
 
  // Triple-click style line selection. With semantic prompt boundaries enabled,
  // this selects only the input area rather than the leading "$ " prompt.
  GhosttyTerminalSelectLineOptions line = GHOSTTY_INIT_SIZED(GhosttyTerminalSelectLineOptions);
  line.ref = ref_at(terminal, 2, 0); // the "git status" input area
  line.semantic_prompt_boundary = true;
  result = ghostty_terminal_select_line(terminal, &line, &selection);
  assert(result == GHOSTTY_SUCCESS);
  print_selection(terminal, "line", &selection);
 
  // Select exactly the command output for the command under the cursor.
  result = ghostty_terminal_select_output(
      terminal, ref_at(terminal, 0, 1), &selection);
  assert(result == GHOSTTY_SUCCESS);
  print_selection(terminal, "output", &selection);
 
  // Select all visible content.
  result = ghostty_terminal_select_all(terminal, &selection);
  assert(result == GHOSTTY_SUCCESS);
  print_selection(terminal, "all", &selection);
 
  ghostty_terminal_free(terminal);
  return 0;
}

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);
 
  // 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;
}

Typedefs
typedef struct GhosttySelectionGestureImpl *	GhosttySelectionGesture
typedef struct GhosttySelectionGestureEventImpl *	GhosttySelectionGestureEvent

Enumerations
enum	GhosttySelectionOrder { GHOSTTY_SELECTION_ORDER_FORWARD = 0 , GHOSTTY_SELECTION_ORDER_REVERSE = 1 , GHOSTTY_SELECTION_ORDER_MIRRORED_FORWARD = 2 , GHOSTTY_SELECTION_ORDER_MIRRORED_REVERSE = 3 , GHOSTTY_SELECTION_ORDER_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttySelectionAdjust {   GHOSTTY_SELECTION_ADJUST_LEFT = 0 , GHOSTTY_SELECTION_ADJUST_RIGHT = 1 , GHOSTTY_SELECTION_ADJUST_UP = 2 , GHOSTTY_SELECTION_ADJUST_DOWN = 3 ,   GHOSTTY_SELECTION_ADJUST_HOME = 4 , GHOSTTY_SELECTION_ADJUST_END = 5 , GHOSTTY_SELECTION_ADJUST_PAGE_UP = 6 , GHOSTTY_SELECTION_ADJUST_PAGE_DOWN = 7 ,   GHOSTTY_SELECTION_ADJUST_BEGINNING_OF_LINE = 8 , GHOSTTY_SELECTION_ADJUST_END_OF_LINE = 9 , GHOSTTY_SELECTION_ADJUST_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttySelectionGestureBehavior { GHOSTTY_SELECTION_GESTURE_BEHAVIOR_CELL = 0 , GHOSTTY_SELECTION_GESTURE_BEHAVIOR_WORD = 1 , GHOSTTY_SELECTION_GESTURE_BEHAVIOR_LINE = 2 , GHOSTTY_SELECTION_GESTURE_BEHAVIOR_OUTPUT = 3 , GHOSTTY_SELECTION_GESTURE_BEHAVIOR_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttySelectionGestureAutoscroll { GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_NONE = 0 , GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_UP = 1 , GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_DOWN = 2 , GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttySelectionGestureData {   GHOSTTY_SELECTION_GESTURE_DATA_CLICK_COUNT = 0 , GHOSTTY_SELECTION_GESTURE_DATA_DRAGGED = 1 , GHOSTTY_SELECTION_GESTURE_DATA_AUTOSCROLL = 2 , GHOSTTY_SELECTION_GESTURE_DATA_BEHAVIOR = 3 ,   GHOSTTY_SELECTION_GESTURE_DATA_ANCHOR = 4 , GHOSTTY_SELECTION_GESTURE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttySelectionGestureEventType {   GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS = 0 , GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE = 1 , GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG = 2 , GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_AUTOSCROLL_TICK = 3 ,   GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS = 4 , GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttySelectionGestureEventOption {   GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF = 0 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION = 1 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_DISTANCE = 2 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_TIME_NS = 3 ,   GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_INTERVAL_NS = 4 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_WORD_BOUNDARY_CODEPOINTS = 5 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_BEHAVIORS = 6 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_RECTANGLE = 7 ,   GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY = 8 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_VIEWPORT = 9 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }

Functions
GHOSTTY_API GhosttyResult	ghostty_selection_gesture_event_new (const GhosttyAllocator *allocator, GhosttySelectionGestureEvent *out_event, GhosttySelectionGestureEventType type)
GHOSTTY_API void	ghostty_selection_gesture_event_free (GhosttySelectionGestureEvent event)
GHOSTTY_API GhosttyResult	ghostty_selection_gesture_event_set (GhosttySelectionGestureEvent event, GhosttySelectionGestureEventOption option, const void *value)
GHOSTTY_API GhosttyResult	ghostty_selection_gesture_event (GhosttySelectionGesture gesture, GhosttyTerminal terminal, GhosttySelectionGestureEvent event, GhosttySelection *out_selection)
GHOSTTY_API GhosttyResult	ghostty_selection_gesture_new (const GhosttyAllocator *allocator, GhosttySelectionGesture *out_gesture)
GHOSTTY_API void	ghostty_selection_gesture_free (GhosttySelectionGesture gesture, GhosttyTerminal terminal)
GHOSTTY_API void	ghostty_selection_gesture_reset (GhosttySelectionGesture gesture, GhosttyTerminal terminal)
GHOSTTY_API GhosttyResult	ghostty_selection_gesture_get (GhosttySelectionGesture gesture, GhosttyTerminal terminal, GhosttySelectionGestureData data, void *value)
GHOSTTY_API GhosttyResult	ghostty_selection_gesture_get_multi (GhosttySelectionGesture gesture, GhosttyTerminal terminal, size_t count, const GhosttySelectionGestureData *keys, void **values, size_t *out_written)
GHOSTTY_API GhosttyResult	ghostty_terminal_select_word (GhosttyTerminal terminal, const GhosttyTerminalSelectWordOptions *options, GhosttySelection *out_selection)
GHOSTTY_API GhosttyResult	ghostty_terminal_select_word_between (GhosttyTerminal terminal, const GhosttyTerminalSelectWordBetweenOptions *options, GhosttySelection *out_selection)
GHOSTTY_API GhosttyResult	ghostty_terminal_select_line (GhosttyTerminal terminal, const GhosttyTerminalSelectLineOptions *options, GhosttySelection *out_selection)
GHOSTTY_API GhosttyResult	ghostty_terminal_select_all (GhosttyTerminal terminal, GhosttySelection *out_selection)
GHOSTTY_API GhosttyResult	ghostty_terminal_select_output (GhosttyTerminal terminal, GhosttyGridRef ref, GhosttySelection *out_selection)
GHOSTTY_API GhosttyResult	ghostty_terminal_selection_format_buf (GhosttyTerminal terminal, GhosttyTerminalSelectionFormatOptions options, uint8_t *buf, size_t buf_len, size_t *out_written)
GHOSTTY_API GhosttyResult	ghostty_terminal_selection_format_alloc (GhosttyTerminal terminal, const GhosttyAllocator *allocator, GhosttyTerminalSelectionFormatOptions options, uint8_t **out_ptr, size_t *out_len)
GHOSTTY_API GhosttyResult	ghostty_terminal_selection_adjust (GhosttyTerminal terminal, GhosttySelection *selection, GhosttySelectionAdjust adjustment)
GHOSTTY_API GhosttyResult	ghostty_terminal_selection_order (GhosttyTerminal terminal, const GhosttySelection *selection, GhosttySelectionOrder *out_order)
GHOSTTY_API GhosttyResult	ghostty_terminal_selection_ordered (GhosttyTerminal terminal, const GhosttySelection *selection, GhosttySelectionOrder desired, GhosttySelection *out_selection)
GHOSTTY_API GhosttyResult	ghostty_terminal_selection_contains (GhosttyTerminal terminal, const GhosttySelection *selection, GhosttyPoint point, bool *out_contains)
GHOSTTY_API GhosttyResult	ghostty_terminal_selection_equal (GhosttyTerminal terminal, const GhosttySelection *a, const GhosttySelection *b, bool *out_equal)

Data Structures
struct	GhosttySelection
struct	GhosttyTerminalSelectWordOptions
struct	GhosttyTerminalSelectWordBetweenOptions
struct	GhosttyTerminalSelectLineOptions
struct	GhosttyTerminalSelectionFormatOptions
struct	GhosttySelectionGestureBehaviors
struct	GhosttySelectionGestureGeometry

Typedef Documentation

GhosttySelectionGesture

typedef struct GhosttySelectionGestureImpl* GhosttySelectionGesture

Opaque handle to state for interpreting terminal selection gestures.

The gesture owns only the state required to interpret pointer events. Calls that use a gesture are not concurrency-safe and must be serialized with terminal mutations.

Examples

c-vt-selection-gesture/src/main.c.

Definition at line 61 of file selection.h.

GhosttySelectionGestureEvent

typedef struct GhosttySelectionGestureEventImpl* GhosttySelectionGestureEvent

Opaque handle to reusable input data for selection gesture operations.

Event options are set with ghostty_selection_gesture_event_set(). Individual gesture operations document which options are required or optional.

Examples

c-vt-selection-gesture/src/main.c.

Definition at line 71 of file selection.h.

Enumeration Type Documentation

GhosttySelectionAdjust

enum GhosttySelectionAdjust

Operation used to adjust a selection endpoint.

Adjustment mutates the selection's logical end endpoint, not whichever endpoint is visually bottom/right. This preserves keyboard and drag behavior for both forward and reversed selections.

Enumerator
GHOSTTY_SELECTION_ADJUST_LEFT	Move left to the previous non-empty cell, wrapping upward.
GHOSTTY_SELECTION_ADJUST_RIGHT	Move right to the next non-empty cell, wrapping downward.
GHOSTTY_SELECTION_ADJUST_UP	Move up one row at the current column, or to the beginning of the line if already at the top.
GHOSTTY_SELECTION_ADJUST_DOWN	Move down to the next non-blank row at the current column, or to the end of the line if none exists.
GHOSTTY_SELECTION_ADJUST_HOME	Move to the top-left cell of the screen.
GHOSTTY_SELECTION_ADJUST_END	Move to the right edge of the last non-blank row on the screen.
GHOSTTY_SELECTION_ADJUST_PAGE_UP	Move up by one terminal page height, or to home if that would move past the top.
GHOSTTY_SELECTION_ADJUST_PAGE_DOWN	Move down by one terminal page height, or to end if that would move past the bottom.
GHOSTTY_SELECTION_ADJUST_BEGINNING_OF_LINE	Move to the left edge of the current line.
GHOSTTY_SELECTION_ADJUST_END_OF_LINE	Move to the right edge of the current line.

Definition at line 271 of file selection.h.

GhosttySelectionGestureAutoscroll

enum GhosttySelectionGestureAutoscroll

Current autoscroll direction for an active selection drag gesture.

Enumerator
GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_NONE	No selection autoscroll is requested.
GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_UP	Selection dragging should autoscroll the viewport upward.
GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_DOWN	Selection dragging should autoscroll the viewport downward.

Definition at line 378 of file selection.h.

GhosttySelectionGestureBehavior

enum GhosttySelectionGestureBehavior

Selection behavior chosen for a gesture's click sequence.

Enumerator
GHOSTTY_SELECTION_GESTURE_BEHAVIOR_CELL	Cell-granular drag selection.
GHOSTTY_SELECTION_GESTURE_BEHAVIOR_WORD	Word selection on press and word-granular drag selection.
GHOSTTY_SELECTION_GESTURE_BEHAVIOR_LINE	Line selection on press and line-granular drag selection.
GHOSTTY_SELECTION_GESTURE_BEHAVIOR_OUTPUT	Semantic command output selection on press and drag.

Definition at line 322 of file selection.h.

GhosttySelectionGestureData

enum GhosttySelectionGestureData

Data fields readable from a selection gesture with ghostty_selection_gesture_get().

Enumerator
GHOSTTY_SELECTION_GESTURE_DATA_CLICK_COUNT	Current click count: uint8_t*. 0 means inactive.
GHOSTTY_SELECTION_GESTURE_DATA_DRAGGED	Whether the current/last left-click gesture has dragged: bool*.
GHOSTTY_SELECTION_GESTURE_DATA_AUTOSCROLL	Current autoscroll request: GhosttySelectionGestureAutoscroll*.
GHOSTTY_SELECTION_GESTURE_DATA_BEHAVIOR	Current gesture behavior: GhosttySelectionGestureBehavior*.
GHOSTTY_SELECTION_GESTURE_DATA_ANCHOR	Current left-click anchor: GhosttyGridRef*. Returns GHOSTTY_NO_VALUE if there is no valid active anchor. On success, writes an untracked GhosttyGridRef snapshot with normal GhosttyGridRef lifetime rules.

Definition at line 397 of file selection.h.

GhosttySelectionGestureEventOption

enum GhosttySelectionGestureEventOption

Options stored on a reusable selection gesture event.

Passing NULL as the value to ghostty_selection_gesture_event_set() clears the corresponding option.

Enumerator
GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF	Grid reference under the pointer: GhosttyGridRef*. Required for PRESS and DRAG events. Optional for RELEASE events; when unset or cleared, release records that the pointer did not map to a valid cell.
GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION	Surface-space pointer position: GhosttySurfacePosition*. Valid for PRESS, DRAG, and AUTOSCROLL_TICK.
GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_DISTANCE	Maximum repeat-click distance in pixels: double*.
GHOSTTY_SELECTION_GESTURE_EVENT_OPT_TIME_NS	Optional monotonic event time in nanoseconds: uint64_t*. If unset, press treats the event as untimed and only single-click behavior is available.
GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_INTERVAL_NS	Maximum interval between repeat clicks in nanoseconds: uint64_t*.
GHOSTTY_SELECTION_GESTURE_EVENT_OPT_WORD_BOUNDARY_CODEPOINTS	Word-boundary codepoints: GhosttyCodepoints*. The codepoints are copied into event-owned storage when set. If unset, operations that need word boundaries use Ghostty's defaults. Valid for PRESS, DRAG, AUTOSCROLL_TICK, and DEEP_PRESS.
GHOSTTY_SELECTION_GESTURE_EVENT_OPT_BEHAVIORS	Selection behavior table: GhosttySelectionGestureBehaviors*. If unset, press uses the default behavior table: cell, word, line.
GHOSTTY_SELECTION_GESTURE_EVENT_OPT_RECTANGLE	Whether a drag or autoscroll tick should produce a rectangular selection: bool*.
GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY	Drag display geometry: GhosttySelectionGestureGeometry*. Required for DRAG and AUTOSCROLL_TICK.
GHOSTTY_SELECTION_GESTURE_EVENT_OPT_VIEWPORT	Viewport coordinate for an autoscroll tick: GhosttyPointCoordinate*. Required for AUTOSCROLL_TICK.

Definition at line 457 of file selection.h.

GhosttySelectionGestureEventType

enum GhosttySelectionGestureEventType

Selection gesture event type.

The event type is fixed when the event is created. Each event type documents which options are valid and which options are required by gesture operations.

Enumerator
GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS	Press event for ghostty_selection_gesture_event().
GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE	Release event for ghostty_selection_gesture_event().
GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG	Drag event for ghostty_selection_gesture_event().
GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_AUTOSCROLL_TICK	Autoscroll tick event for ghostty_selection_gesture_event().
GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS	Deep press event for ghostty_selection_gesture_event().

Examples

c-vt-selection-gesture/src/main.c.

Definition at line 430 of file selection.h.

GhosttySelectionOrder

enum GhosttySelectionOrder

Ordering of a selection's endpoints in terminal coordinates.

Mirrored orders are only produced by rectangular selections whose start and end endpoints are on opposite diagonal corners that are not simple top-left-to-bottom-right or bottom-right-to-top-left orderings.

Enumerator
GHOSTTY_SELECTION_ORDER_FORWARD	Start is before end in top-left to bottom-right order.
GHOSTTY_SELECTION_ORDER_REVERSE	End is before start in top-left to bottom-right order.
GHOSTTY_SELECTION_ORDER_MIRRORED_FORWARD	Rectangular selection from top-right to bottom-left.
GHOSTTY_SELECTION_ORDER_MIRRORED_REVERSE	Rectangular selection from bottom-left to top-right.

Definition at line 246 of file selection.h.

Function Documentation

ghostty_selection_gesture_event()

GHOSTTY_API GhosttyResult ghostty_selection_gesture_event	(	GhosttySelectionGesture	gesture,
		GhosttyTerminal	terminal,
		GhosttySelectionGestureEvent	event,
		GhosttySelection *	out_selection )

Apply a selection gesture event and return the resulting selection snapshot.

This dispatches to the gesture operation matching the event's fixed type. For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS, the event must have GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF set before calling this function. All other press options use their initialized defaults when unset or cleared.

For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE, only GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF is valid. It is optional; if unset or cleared, release records that the pointer did not map to a valid cell. Release events update gesture state but do not produce a selection, so this function returns GHOSTTY_NO_VALUE after applying them.

For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF and GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY are required. Position, rectangle, and word-boundary codepoints are optional and use initialized defaults when unset or cleared.

For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_AUTOSCROLL_TICK, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_VIEWPORT and GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY are required. Position, rectangle, and word-boundary codepoints are optional and use initialized defaults when unset or cleared.

For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS, only GHOSTTY_SELECTION_GESTURE_EVENT_OPT_WORD_BOUNDARY_CODEPOINTS is valid. It is optional and uses initialized defaults when unset or cleared.

The returned selection is not installed as the terminal's current selection. It is a snapshot with the same lifetime rules as GhosttySelection.

Parameters

	gesture	Selection gesture handle (NULL returns GHOSTTY_INVALID_VALUE)
	Terminal	Terminal used to interpret and update gesture state
	event	Selection gesture event handle (NULL returns GHOSTTY_INVALID_VALUE)
[out]	out_selection	On success, receives the resulting selection. May be NULL to apply the event and discard the selection result.

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the event does not currently produce a selection, GHOSTTY_OUT_OF_MEMORY if tracking gesture state fails, or GHOSTTY_INVALID_VALUE if gesture, terminal, event, or required event data is invalid

Examples

c-vt-selection-gesture/src/main.c.

ghostty_selection_gesture_event_free()

GHOSTTY_API void ghostty_selection_gesture_event_free

(

GhosttySelectionGestureEvent

event

)

Free a selection gesture event object.

Passing NULL is allowed and is a no-op.

Parameters

event

Selection gesture event handle to free

Examples

c-vt-selection-gesture/src/main.c.

ghostty_selection_gesture_event_new()

GHOSTTY_API GhosttyResult ghostty_selection_gesture_event_new	(	const GhosttyAllocator *	allocator,
		GhosttySelectionGestureEvent *	out_event,
		GhosttySelectionGestureEventType	type )

Create a reusable selection gesture event object.

Parameters

Memory Management	Allocator, or NULL for the default allocator
out_event	Receives the created event handle
type	Event type. This is fixed for the lifetime of the event.

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if out_event is NULL or type is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation fails

Examples

c-vt-selection-gesture/src/main.c.

ghostty_selection_gesture_event_set()

GHOSTTY_API GhosttyResult ghostty_selection_gesture_event_set	(	GhosttySelectionGestureEvent	event,
		GhosttySelectionGestureEventOption	option,
		const void *	value )

Set or clear an option on a selection gesture event.

The value type depends on option and is documented by GhosttySelectionGestureEventOption. Passing NULL for value clears the option.

Parameters

event	Selection gesture event handle (NULL returns GHOSTTY_INVALID_VALUE)
option	Event option to set or clear
value	Pointer to the input value for option, or NULL to clear

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY if copying event-owned data fails, or GHOSTTY_INVALID_VALUE if event, option, or value is invalid

Examples

c-vt-selection-gesture/src/main.c.

ghostty_selection_gesture_free()

GHOSTTY_API void ghostty_selection_gesture_free	(	GhosttySelectionGesture	gesture,
		GhosttyTerminal	terminal )

Free a selection gesture object.

This releases any tracked terminal references owned by the gesture using the provided terminal, then frees the gesture object. Passing NULL for gesture is allowed and is a no-op.

If the terminal is still alive, pass the terminal most recently used with the gesture so any tracked terminal references can be released correctly. If the terminal has already been freed, pass NULL for terminal; the terminal's page storage has already released the underlying tracked references, so the gesture wrapper can be safely discarded without touching the stale terminal state.

Parameters

gesture	Selection gesture handle to free
Terminal	Terminal used to release tracked gesture state, or NULL if the terminal has already been freed

Examples

c-vt-selection-gesture/src/main.c.

ghostty_selection_gesture_get()

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

Read data from a selection gesture.

The type of value depends on data and is documented by GhosttySelectionGestureData. For GHOSTTY_SELECTION_GESTURE_DATA_ANCHOR, the returned GhosttyGridRef is an untracked snapshot with normal grid-ref lifetime rules.

Parameters

gesture	Selection gesture handle (NULL returns GHOSTTY_INVALID_VALUE)
Terminal	Terminal used to validate terminal-backed gesture state
data	Data field to read
value	Output pointer whose type depends on data

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the requested data has no value, or GHOSTTY_INVALID_VALUE if gesture, terminal, data, or value is invalid

Examples

c-vt-selection-gesture/src/main.c.

ghostty_selection_gesture_get_multi()

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

Read multiple data fields from a selection gesture in a single call.

This is an optimization over calling ghostty_selection_gesture_get() multiple times. Each entry in values must point to storage of the type documented by the corresponding GhosttySelectionGestureData key.

If any individual read fails, the function returns that error and writes the index of the failing key to out_written when out_written is non-NULL. On success, out_written receives count when non-NULL.

Parameters

gesture	Selection gesture handle (NULL returns GHOSTTY_INVALID_VALUE)
Terminal	Terminal used to validate terminal-backed gesture state
count	Number of data fields to read
keys	Data fields to read (must not be NULL)
values	Output pointers corresponding to keys (must not be NULL)
out_written	Optional number of fields read, or failing index on error

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if a requested data field has no value, or GHOSTTY_INVALID_VALUE if gesture, terminal, keys, values, or a value pointer is invalid

ghostty_selection_gesture_new()

GHOSTTY_API GhosttyResult ghostty_selection_gesture_new	(	const GhosttyAllocator *	allocator,
		GhosttySelectionGesture *	out_gesture )

Create a selection gesture object.

The gesture stores mutable state for terminal text selection gestures. The gesture is not bound to a terminal at creation time; terminal-dependent APIs take the terminal explicitly.

Parameters

Memory Management	Allocator, or NULL for the default allocator
out_gesture	Receives the created gesture handle

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if out_gesture is NULL, or GHOSTTY_OUT_OF_MEMORY if allocation fails

Examples

c-vt-selection-gesture/src/main.c.

ghostty_selection_gesture_reset()

GHOSTTY_API void ghostty_selection_gesture_reset	(	GhosttySelectionGesture	gesture,
		GhosttyTerminal	terminal )

Reset any active selection gesture state.

This cancels the active click sequence and releases any tracked terminal references owned by the gesture without freeing the gesture object. Passing NULL is allowed and is a no-op.

Parameters

gesture	Selection gesture handle to reset
Terminal	Terminal used to release tracked gesture state

Examples

c-vt-selection-gesture/src/main.c.

ghostty_terminal_select_all()

GHOSTTY_API GhosttyResult ghostty_terminal_select_all	(	GhosttyTerminal	terminal,
		GhosttySelection *	out_selection )

Derive a selection snapshot covering all selectable terminal content.

The returned selection is not installed as the terminal's current selection. It is a snapshot with the same lifetime rules as GhosttySelection.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
[out]	out_selection	On success, receives the derived selection

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if there is no selectable content, or GHOSTTY_INVALID_VALUE if the terminal or output pointer is invalid.

ghostty_terminal_select_line()

GHOSTTY_API GhosttyResult ghostty_terminal_select_line	(	GhosttyTerminal	terminal,
		const GhosttyTerminalSelectLineOptions *	options,
		GhosttySelection *	out_selection )

Derive a line selection snapshot from a terminal grid reference.

The returned selection is not installed as the terminal's current selection. It is a snapshot with the same lifetime rules as GhosttySelection.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	options	Line-selection options
[out]	out_selection	On success, receives the derived selection

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the valid ref has no selectable line content, or GHOSTTY_INVALID_VALUE if the terminal, options, ref, codepoint pointer, or output pointer are invalid.

ghostty_terminal_select_output()

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

Derive a command-output selection snapshot from a terminal grid reference.

The returned selection is not installed as the terminal's current selection. It is a snapshot with the same lifetime rules as GhosttySelection.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	ref	Grid reference within command output to select
[out]	out_selection	On success, receives the derived selection

Returns

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

ghostty_terminal_select_word()

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

Derive a word selection snapshot from a terminal grid reference.

The returned selection is not installed as the terminal's current selection. It is a snapshot with the same lifetime rules as GhosttySelection.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	options	Word-selection options
[out]	out_selection	On success, receives the derived selection

Returns

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

ghostty_terminal_select_word_between()

GHOSTTY_API GhosttyResult ghostty_terminal_select_word_between	(	GhosttyTerminal	terminal,
		const GhosttyTerminalSelectWordBetweenOptions *	options,
		GhosttySelection *	out_selection )

Derive the nearest word selection snapshot between two terminal grid refs.

Starting at options->start, this searches toward options->end (inclusive) and returns the first selectable word found using Ghostty's word-selection rules.

This is useful for implementing double-click-and-drag selection in a UI. If a user double-clicks one word and drags across spaces or punctuation toward another word, selecting only the word directly under the current pointer can flicker or collapse when the pointer is between words. Instead, ask for the nearest word between the original click and the drag point, ask again in the reverse direction, and combine the two word bounds into the drag selection.

  // Double-click-and-drag style selection. Suppose the user double-clicks
  // "git" and drags to "status". The pointer may pass over whitespace, so
  // select the nearest word between the original click and current drag point
  // in both directions, then combine the outer word bounds.
  GhosttyGridRef click_ref = ref_at(terminal, 2, 0); // the "git" in "git status"
  GhosttyGridRef drag_ref = ref_at(terminal, 6, 0);  // the "status" in "git status"
 
  GhosttyTerminalSelectWordBetweenOptions start_word_opts =
      GHOSTTY_INIT_SIZED(GhosttyTerminalSelectWordBetweenOptions);
  start_word_opts.start = click_ref;
  start_word_opts.end = drag_ref;
 
  GhosttySelection start_word = GHOSTTY_INIT_SIZED(GhosttySelection);
  result = ghostty_terminal_select_word_between(
      terminal, &start_word_opts, &start_word);
  assert(result == GHOSTTY_SUCCESS);
 
  GhosttyTerminalSelectWordBetweenOptions end_word_opts =
      GHOSTTY_INIT_SIZED(GhosttyTerminalSelectWordBetweenOptions);
  end_word_opts.start = drag_ref;
  end_word_opts.end = click_ref;
 
  GhosttySelection end_word = GHOSTTY_INIT_SIZED(GhosttySelection);
  result = ghostty_terminal_select_word_between(
      terminal, &end_word_opts, &end_word);
  assert(result == GHOSTTY_SUCCESS);
 
  GhosttySelection drag_selection = GHOSTTY_INIT_SIZED(GhosttySelection);
  drag_selection.start = start_word.start;
  drag_selection.end = end_word.end;
  print_selection(terminal, "double-click drag", &drag_selection);

The returned selection is not installed as the terminal's current selection. It is a snapshot with the same lifetime rules as GhosttySelection.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	options	Word-between-selection options
[out]	out_selection	On success, receives the derived selection

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if there is no selectable word content between the valid refs, or GHOSTTY_INVALID_VALUE if the terminal, options, refs, codepoint pointer, or output pointer are invalid.

ghostty_terminal_selection_adjust()

GHOSTTY_API GhosttyResult ghostty_terminal_selection_adjust	(	GhosttyTerminal	terminal,
		GhosttySelection *	selection,
		GhosttySelectionAdjust	adjustment )

Adjust a selection snapshot using terminal selection semantics.

This mutates the caller-provided GhosttySelection in place. The logical end endpoint is always moved, regardless of whether the selection is forward or reversed visually. The input selection remains a snapshot: after adjustment, call ghostty_terminal_set() with GHOSTTY_TERMINAL_OPT_SELECTION to install it as the terminal-owned selection if desired.

The selection's start and end grid refs must both be valid untracked snapshots for the given terminal's currently active screen. In practice, they must come from that terminal and screen, and no mutating terminal call may have occurred since the refs were produced or reconstructed from tracked refs. Passing refs from another terminal, another screen, or stale refs violates this precondition.

Parameters

Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
Selection	Selection snapshot to adjust in place
adjustment	The adjustment operation to apply

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal, selection, or adjustment are invalid. Selection reference validity is a precondition and is not checked.

ghostty_terminal_selection_contains()

GHOSTTY_API GhosttyResult ghostty_terminal_selection_contains	(	GhosttyTerminal	terminal,
		const GhosttySelection *	selection,
		GhosttyPoint	point,
		bool *	out_contains )

Test whether a terminal point is inside a selection snapshot.

This uses the same selection semantics as the terminal, including rectangular/block selections and linear selections spanning multiple rows.

The selection's start and end grid refs must both be valid untracked snapshots for the given terminal's currently active screen. In practice, they must come from that terminal and screen, and no mutating terminal call may have occurred since the refs were produced or reconstructed from tracked refs. Passing refs from another terminal, another screen, or stale refs violates this precondition.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	Selection	Selection snapshot to inspect
	Point	Point to test for containment
[out]	out_contains	On success, receives whether point is inside selection

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal, selection, point, or output pointer are invalid. Selection reference validity is a precondition and is not checked.

ghostty_terminal_selection_equal()

GHOSTTY_API GhosttyResult ghostty_terminal_selection_equal	(	GhosttyTerminal	terminal,
		const GhosttySelection *	a,
		const GhosttySelection *	b,
		bool *	out_equal )

Test whether two selection snapshots are equal.

Equality uses the terminal's internal selection semantics: both endpoint pins must match and both selections must have the same rectangular/block state. This avoids requiring callers to compare raw GhosttyGridRef internals.

Both selections' start and end grid refs must be valid untracked snapshots for the given terminal's currently active screen. In practice, they must come from that terminal and screen, and no mutating terminal call may have occurred since the refs were produced or reconstructed from tracked refs. Passing refs from another terminal, another screen, or stale refs violates this precondition.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	a	First selection snapshot to compare
	b	Second selection snapshot to compare
[out]	out_equal	On success, receives whether the selections are equal

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal, selections, or output pointer are invalid. Selection reference validity is a precondition and is not checked.

ghostty_terminal_selection_format_alloc()

GHOSTTY_API GhosttyResult ghostty_terminal_selection_format_alloc	(	GhosttyTerminal	terminal,
		const GhosttyAllocator *	allocator,
		GhosttyTerminalSelectionFormatOptions	options,
		uint8_t **	out_ptr,
		size_t *	out_len )

Format a terminal selection into an allocated buffer.

This is a one-shot convenience API for formatting either the terminal's active selection or a caller-provided GhosttySelection without explicitly creating a GhosttyFormatter.

The returned buffer is allocated using allocator, or the default allocator if NULL is passed. The caller owns the returned buffer and must free it with ghostty_free(), passing the same allocator and returned length.

The returned bytes are not NUL-terminated. This supports plain text, VT, and HTML uniformly as byte output.

If options.selection is NULL and the terminal has no active selection, the function returns GHOSTTY_NO_VALUE and leaves out_ptr as NULL and out_len as 0.

Parameters

Terminal	The terminal to read from (must not be NULL)
Memory Management	Allocator used for the returned buffer, or NULL for the default allocator
options	Selection formatting options
out_ptr	Receives the allocated output buffer (must not be NULL)
out_len	Receives the output length in bytes (must not be NULL)

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

Examples

c-vt-selection-gesture/src/main.c.

ghostty_terminal_selection_format_buf()

GHOSTTY_API GhosttyResult ghostty_terminal_selection_format_buf	(	GhosttyTerminal	terminal,
		GhosttyTerminalSelectionFormatOptions	options,
		uint8_t *	buf,
		size_t	buf_len,
		size_t *	out_written )

Format a terminal selection into a caller-provided buffer.

This is a one-shot convenience API for formatting either the terminal's active selection or a caller-provided GhosttySelection without explicitly creating a GhosttyFormatter.

Pass NULL for buf to query the required output size. In that case, out_written receives the required size and the function returns GHOSTTY_OUT_OF_SPACE.

If buf is too small, the function returns GHOSTTY_OUT_OF_SPACE and writes the required size to out_written. The caller can then retry with a larger buffer.

If options.selection is NULL and the terminal has no active selection, the function returns GHOSTTY_NO_VALUE.

Parameters

Terminal	The terminal to read from (must not be NULL)
options	Selection formatting options
buf	Output buffer, or NULL to query required size
buf_len	Length of buf in bytes
out_written	Number of bytes written, or required size on GHOSTTY_OUT_OF_SPACE (must not be NULL)

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

ghostty_terminal_selection_order()

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

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. In practice, they must come from that terminal and screen, and no mutating terminal call may have occurred since the refs were produced or reconstructed from tracked refs. Passing refs from another terminal, another screen, or stale refs violates this precondition.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	Selection	Selection snapshot to inspect
[out]	out_order	On success, receives the selection order

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal, selection, or output pointer are invalid. Selection reference validity is a precondition and is not checked.

ghostty_terminal_selection_ordered()

GHOSTTY_API GhosttyResult ghostty_terminal_selection_ordered	(	GhosttyTerminal	terminal,
		const GhosttySelection *	selection,
		GhosttySelectionOrder	desired,
		GhosttySelection *	out_selection )

Return a selection snapshot with endpoints ordered as requested.

Use GHOSTTY_SELECTION_ORDER_FORWARD to get top-left to bottom-right bounds, and GHOSTTY_SELECTION_ORDER_REVERSE to get bottom-right to top-left bounds. Mirrored desired orders are accepted but normalized the same as forward. The output selection is a fresh untracked snapshot and is not installed as the terminal's current selection.

The selection's start and end grid refs must both be valid untracked snapshots for the given terminal's currently active screen. In practice, they must come from that terminal and screen, and no mutating terminal call may have occurred since the refs were produced or reconstructed from tracked refs. Passing refs from another terminal, another screen, or stale refs violates this precondition.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	Selection	Selection snapshot to order
	desired	Desired endpoint order
[out]	out_selection	On success, receives the ordered selection

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal, selection, desired order, or output pointer are invalid. Selection reference validity is a precondition and is not checked.