/** * @file selection.h * * Selection range type for specifying a region of terminal content. */ #ifndef GHOSTTY_VT_SELECTION_H#define GHOSTTY_VT_SELECTION_H #include <stdbool.h>#include <stddef.h>#include <stdint.h>#include <ghostty/vt/allocator.h>#include <ghostty/vt/grid_ref.h>#include <ghostty/vt/point.h>#include <ghostty/vt/types.h> #ifdef __cplusplusextern "C" {#endif /** @defgroup selection Selection * * 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 * * @snippet c-vt-selection/src/main.c selection-main * @snippet c-vt-selection-gesture/src/main.c selection-gesture-main * * @{ */ /** * 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. * * @ingroup selection */typedef struct GhosttySelectionGestureImpl* GhosttySelectionGesture; /** * 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. * * @ingroup selection */typedef struct GhosttySelectionGestureEventImpl* GhosttySelectionGestureEvent; /** * A snapshot selection range defined by two grid references. * * Both endpoints are inclusive. The endpoints preserve selection direction * and may be reversed; callers must not assume that start is the top-left * endpoint or that end is the bottom-right endpoint. * * When rectangle is false, the endpoints describe a linear selection. When * rectangle is true, the same endpoints are interpreted as opposite corners * of a rectangular/block selection. * * The start and end values are untracked GhosttyGridRef snapshots and are * only valid until the next mutating operation on the terminal that produced * them unless the selection is reconstructed from tracked references. * * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it. * * @ingroup selection */typedef struct { /** Size of this struct in bytes. Must be set to sizeof(GhosttySelection). */ size_t size; /** * Start of the selection range (inclusive). * * This may be after end in terminal order. It is an untracked * GhosttyGridRef snapshot and follows untracked grid-ref lifetime rules. */ GhosttyGridRef start; /** * End of the selection range (inclusive). * * This may be before start in terminal order. It is an untracked * GhosttyGridRef snapshot and follows untracked grid-ref lifetime rules. */ GhosttyGridRef end; /** * Whether the endpoints are interpreted as a rectangular/block selection * rather than a linear selection. */ bool rectangle;} GhosttySelection; /** * Options for deriving a word selection from a terminal grid reference. * * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it. * If boundary_codepoints is NULL and boundary_codepoints_len is 0, Ghostty's * default word-boundary codepoints are used. If boundary_codepoints_len is * non-zero, boundary_codepoints must not be NULL. * * @ingroup selection */typedef struct { /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectWordOptions). */ size_t size; /** Grid reference under which to derive the word selection. */ GhosttyGridRef ref; /** Optional word-boundary codepoints as uint32_t scalar values. */ const uint32_t* boundary_codepoints; /** Number of entries in boundary_codepoints. */ size_t boundary_codepoints_len;} GhosttyTerminalSelectWordOptions; /** * Options for deriving the nearest word selection between two grid references. * * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it. * If boundary_codepoints is NULL and boundary_codepoints_len is 0, Ghostty's * default word-boundary codepoints are used. If boundary_codepoints_len is * non-zero, boundary_codepoints must not be NULL. * * @ingroup selection */typedef struct { /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectWordBetweenOptions). */ size_t size; /** Starting grid reference for the inclusive search range. */ GhosttyGridRef start; /** Ending grid reference for the inclusive search range. */ GhosttyGridRef end; /** Optional word-boundary codepoints as uint32_t scalar values. */ const uint32_t* boundary_codepoints; /** Number of entries in boundary_codepoints. */ size_t boundary_codepoints_len;} GhosttyTerminalSelectWordBetweenOptions; /** * Options for deriving a line selection from a terminal grid reference. * * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it. * If whitespace is NULL and whitespace_len is 0, Ghostty's default line-trim * whitespace codepoints are used. If whitespace_len is non-zero, whitespace * must not be NULL. * * @ingroup selection */typedef struct { /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectLineOptions). */ size_t size; /** Grid reference under which to derive the line selection. */ GhosttyGridRef ref; /** Optional codepoints to trim from the start and end of the line. */ const uint32_t* whitespace; /** Number of entries in whitespace. */ size_t whitespace_len; /** Whether semantic prompt state changes should bound the line selection. */ bool semantic_prompt_boundary;} GhosttyTerminalSelectLineOptions; /** * Options for one-shot formatting of a terminal selection. * * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it. * * If selection is NULL, the terminal's current active selection is used. * If selection is non-NULL, that caller-provided snapshot selection is used. * * The selection is formatted from the terminal's active screen using the same * formatting semantics as GhosttyFormatter. For copy/clipboard behavior * matching Ghostty's Screen.selectionString(), use plain output with unwrap * and trim both set to true. * * @ingroup selection */typedef struct { /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectionFormatOptions). */ size_t size; /** Output format to emit. */ GhosttyFormatterFormat emit; /** Whether to unwrap soft-wrapped lines. */ bool unwrap; /** Whether to trim trailing whitespace on non-blank lines. */ bool trim; /** * Optional selection to format. * * If NULL, the terminal's current active selection is used. If the terminal * has no active selection, formatting returns GHOSTTY_NO_VALUE. * * If non-NULL, the pointed-to selection must be a valid snapshot selection * for this terminal and must obey GhosttySelection lifetime rules. */ const GhosttySelection *selection;} GhosttyTerminalSelectionFormatOptions; /** * 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. * * @ingroup selection */typedef enum GHOSTTY_ENUM_TYPED { /** Start is before end in top-left to bottom-right order. */ GHOSTTY_SELECTION_ORDER_FORWARD = 0, /** End is before start in top-left to bottom-right order. */ GHOSTTY_SELECTION_ORDER_REVERSE = 1, /** Rectangular selection from top-right to bottom-left. */ GHOSTTY_SELECTION_ORDER_MIRRORED_FORWARD = 2, /** Rectangular selection from bottom-left to top-right. */ GHOSTTY_SELECTION_ORDER_MIRRORED_REVERSE = 3, GHOSTTY_SELECTION_ORDER_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,} GhosttySelectionOrder; /** * 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. * * @ingroup selection */typedef enum GHOSTTY_ENUM_TYPED { /** Move left to the previous non-empty cell, wrapping upward. */ GHOSTTY_SELECTION_ADJUST_LEFT = 0, /** Move right to the next non-empty cell, wrapping downward. */ GHOSTTY_SELECTION_ADJUST_RIGHT = 1, /** * Move up one row at the current column, or to the beginning of the * line if already at the top. */ GHOSTTY_SELECTION_ADJUST_UP = 2, /** * 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_DOWN = 3, /** Move to the top-left cell of the screen. */ GHOSTTY_SELECTION_ADJUST_HOME = 4, /** Move to the right edge of the last non-blank row on the screen. */ GHOSTTY_SELECTION_ADJUST_END = 5, /** * Move up by one terminal page height, or to home if that would move * past the top. */ GHOSTTY_SELECTION_ADJUST_PAGE_UP = 6, /** * Move down by one terminal page height, or to end if that would move * past the bottom. */ GHOSTTY_SELECTION_ADJUST_PAGE_DOWN = 7, /** Move to the left edge of the current line. */ GHOSTTY_SELECTION_ADJUST_BEGINNING_OF_LINE = 8, /** Move to the right edge of the current line. */ GHOSTTY_SELECTION_ADJUST_END_OF_LINE = 9, GHOSTTY_SELECTION_ADJUST_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,} GhosttySelectionAdjust; /** * Selection behavior chosen for a gesture's click sequence. * * @ingroup selection */typedef enum GHOSTTY_ENUM_TYPED { /** Cell-granular drag selection. */ GHOSTTY_SELECTION_GESTURE_BEHAVIOR_CELL = 0, /** Word selection on press and word-granular drag selection. */ GHOSTTY_SELECTION_GESTURE_BEHAVIOR_WORD = 1, /** Line selection on press and line-granular drag selection. */ GHOSTTY_SELECTION_GESTURE_BEHAVIOR_LINE = 2, /** Semantic command output selection on press and drag. */ GHOSTTY_SELECTION_GESTURE_BEHAVIOR_OUTPUT = 3, GHOSTTY_SELECTION_GESTURE_BEHAVIOR_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,} GhosttySelectionGestureBehavior; /** * Selection behaviors for single-, double-, and triple-click gestures. * * @ingroup selection */typedef struct { /** Behavior for single-click selection gestures. */ GhosttySelectionGestureBehavior single_click; /** Behavior for double-click selection gestures. */ GhosttySelectionGestureBehavior double_click; /** Behavior for triple-click selection gestures. */ GhosttySelectionGestureBehavior triple_click;} GhosttySelectionGestureBehaviors; /** * Display geometry used to interpret selection gesture drag events. * * @ingroup selection */typedef struct { /** Number of columns in the rendered terminal grid. Must be non-zero. */ uint32_t columns; /** Width of one terminal cell in surface pixels. Must be non-zero. */ uint32_t cell_width; /** Left padding before the terminal grid begins in surface pixels. */ uint32_t padding_left; /** Height of the rendered terminal surface in surface pixels. Must be non-zero. */ uint32_t screen_height;} GhosttySelectionGestureGeometry; /** * Current autoscroll direction for an active selection drag gesture. * * @ingroup selection */typedef enum GHOSTTY_ENUM_TYPED { /** No selection autoscroll is requested. */ GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_NONE = 0, /** Selection dragging should autoscroll the viewport upward. */ GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_UP = 1, /** Selection dragging should autoscroll the viewport downward. */ GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_DOWN = 2, GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,} GhosttySelectionGestureAutoscroll; /** * Data fields readable from a selection gesture with * ghostty_selection_gesture_get(). * * @ingroup selection */typedef enum GHOSTTY_ENUM_TYPED { /** Current click count: uint8_t*. 0 means inactive. */ GHOSTTY_SELECTION_GESTURE_DATA_CLICK_COUNT = 0, /** Whether the current/last left-click gesture has dragged: bool*. */ GHOSTTY_SELECTION_GESTURE_DATA_DRAGGED = 1, /** Current autoscroll request: GhosttySelectionGestureAutoscroll*. */ GHOSTTY_SELECTION_GESTURE_DATA_AUTOSCROLL = 2, /** Current gesture behavior: GhosttySelectionGestureBehavior*. */ GHOSTTY_SELECTION_GESTURE_DATA_BEHAVIOR = 3, /** * 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. */ GHOSTTY_SELECTION_GESTURE_DATA_ANCHOR = 4, GHOSTTY_SELECTION_GESTURE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,} GhosttySelectionGestureData; /** * 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. * * @ingroup selection */typedef enum GHOSTTY_ENUM_TYPED { /** Press event for ghostty_selection_gesture_event(). */ GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS = 0, /** Release event for ghostty_selection_gesture_event(). */ GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE = 1, /** Drag event for ghostty_selection_gesture_event(). */ GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG = 2, /** Autoscroll tick event for ghostty_selection_gesture_event(). */ GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_AUTOSCROLL_TICK = 3, /** Deep press event for ghostty_selection_gesture_event(). */ GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS = 4, GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,} GhosttySelectionGestureEventType; /** * Options stored on a reusable selection gesture event. * * Passing NULL as the value to ghostty_selection_gesture_event_set() clears the * corresponding option. * * @ingroup selection */typedef enum GHOSTTY_ENUM_TYPED { /** * 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_REF = 0, /** * Surface-space pointer position: GhosttySurfacePosition*. * * Valid for PRESS, DRAG, and AUTOSCROLL_TICK. */ GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION = 1, /** Maximum repeat-click distance in pixels: double*. */ GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_DISTANCE = 2, /** * 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_TIME_NS = 3, /** Maximum interval between repeat clicks in nanoseconds: uint64_t*. */ GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_INTERVAL_NS = 4, /** * 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_WORD_BOUNDARY_CODEPOINTS = 5, /** * Selection behavior table: GhosttySelectionGestureBehaviors*. * * If unset, press uses the default behavior table: cell, word, line.Lines 1–500 of 1061. Load more
/** * @file selection.h * * Selection range type for specifying a region of terminal content. */ #ifndef GHOSTTY_VT_SELECTION_H #define GHOSTTY_VT_SELECTION_H #include <stdbool.h> #include <stddef.h> #include <stdint.h> #include <ghostty/vt/allocator.h> #include <ghostty/vt/grid_ref.h> #include <ghostty/vt/point.h> #include <ghostty/vt/types.h> #ifdef __cplusplus extern "C" { #endif /** @defgroup selection Selection * * 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 * * @snippet c-vt-selection/src/main.c selection-main * @snippet c-vt-selection-gesture/src/main.c selection-gesture-main * * @{ */ /** * 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. * * @ingroup selection */ typedef struct GhosttySelectionGestureImpl* GhosttySelectionGesture; /** * 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. * * @ingroup selection */ typedef struct GhosttySelectionGestureEventImpl* GhosttySelectionGestureEvent; /** * A snapshot selection range defined by two grid references. * * Both endpoints are inclusive. The endpoints preserve selection direction * and may be reversed; callers must not assume that start is the top-left * endpoint or that end is the bottom-right endpoint. * * When rectangle is false, the endpoints describe a linear selection. When * rectangle is true, the same endpoints are interpreted as opposite corners * of a rectangular/block selection. * * The start and end values are untracked GhosttyGridRef snapshots and are * only valid until the next mutating operation on the terminal that produced * them unless the selection is reconstructed from tracked references. * * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it. * * @ingroup selection */ typedef struct { /** Size of this struct in bytes. Must be set to sizeof(GhosttySelection). */ size_t size; /** * Start of the selection range (inclusive). * * This may be after end in terminal order. It is an untracked * GhosttyGridRef snapshot and follows untracked grid-ref lifetime rules. */ GhosttyGridRef start; /** * End of the selection range (inclusive). * * This may be before start in terminal order. It is an untracked * GhosttyGridRef snapshot and follows untracked grid-ref lifetime rules. */ GhosttyGridRef end; /** * Whether the endpoints are interpreted as a rectangular/block selection * rather than a linear selection. */ bool rectangle; } GhosttySelection; /** * Options for deriving a word selection from a terminal grid reference. * * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it. * If boundary_codepoints is NULL and boundary_codepoints_len is 0, Ghostty's * default word-boundary codepoints are used. If boundary_codepoints_len is * non-zero, boundary_codepoints must not be NULL. * * @ingroup selection */ typedef struct { /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectWordOptions). */ size_t size; /** Grid reference under which to derive the word selection. */ GhosttyGridRef ref; /** Optional word-boundary codepoints as uint32_t scalar values. */ const uint32_t* boundary_codepoints; /** Number of entries in boundary_codepoints. */ size_t boundary_codepoints_len; } GhosttyTerminalSelectWordOptions; /** * Options for deriving the nearest word selection between two grid references. * * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it. * If boundary_codepoints is NULL and boundary_codepoints_len is 0, Ghostty's * default word-boundary codepoints are used. If boundary_codepoints_len is * non-zero, boundary_codepoints must not be NULL. * * @ingroup selection */ typedef struct { /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectWordBetweenOptions). */ size_t size; /** Starting grid reference for the inclusive search range. */ GhosttyGridRef start; /** Ending grid reference for the inclusive search range. */ GhosttyGridRef end; /** Optional word-boundary codepoints as uint32_t scalar values. */ const uint32_t* boundary_codepoints; /** Number of entries in boundary_codepoints. */ size_t boundary_codepoints_len; } GhosttyTerminalSelectWordBetweenOptions; /** * Options for deriving a line selection from a terminal grid reference. * * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it. * If whitespace is NULL and whitespace_len is 0, Ghostty's default line-trim * whitespace codepoints are used. If whitespace_len is non-zero, whitespace * must not be NULL. * * @ingroup selection */ typedef struct { /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectLineOptions). */ size_t size; /** Grid reference under which to derive the line selection. */ GhosttyGridRef ref; /** Optional codepoints to trim from the start and end of the line. */ const uint32_t* whitespace; /** Number of entries in whitespace. */ size_t whitespace_len; /** Whether semantic prompt state changes should bound the line selection. */ bool semantic_prompt_boundary; } GhosttyTerminalSelectLineOptions; /** * Options for one-shot formatting of a terminal selection. * * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it. * * If selection is NULL, the terminal's current active selection is used. * If selection is non-NULL, that caller-provided snapshot selection is used. * * The selection is formatted from the terminal's active screen using the same * formatting semantics as GhosttyFormatter. For copy/clipboard behavior * matching Ghostty's Screen.selectionString(), use plain output with unwrap * and trim both set to true. * * @ingroup selection */ typedef struct { /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectionFormatOptions). */ size_t size; /** Output format to emit. */ GhosttyFormatterFormat emit; /** Whether to unwrap soft-wrapped lines. */ bool unwrap; /** Whether to trim trailing whitespace on non-blank lines. */ bool trim; /** * Optional selection to format. * * If NULL, the terminal's current active selection is used. If the terminal * has no active selection, formatting returns GHOSTTY_NO_VALUE. * * If non-NULL, the pointed-to selection must be a valid snapshot selection * for this terminal and must obey GhosttySelection lifetime rules. */ const GhosttySelection *selection; } GhosttyTerminalSelectionFormatOptions; /** * 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. * * @ingroup selection */ typedef enum GHOSTTY_ENUM_TYPED { /** Start is before end in top-left to bottom-right order. */ GHOSTTY_SELECTION_ORDER_FORWARD = 0, /** End is before start in top-left to bottom-right order. */ GHOSTTY_SELECTION_ORDER_REVERSE = 1, /** Rectangular selection from top-right to bottom-left. */ GHOSTTY_SELECTION_ORDER_MIRRORED_FORWARD = 2, /** Rectangular selection from bottom-left to top-right. */ GHOSTTY_SELECTION_ORDER_MIRRORED_REVERSE = 3, GHOSTTY_SELECTION_ORDER_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE, } GhosttySelectionOrder; /** * 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. * * @ingroup selection */ typedef enum GHOSTTY_ENUM_TYPED { /** Move left to the previous non-empty cell, wrapping upward. */ GHOSTTY_SELECTION_ADJUST_LEFT = 0, /** Move right to the next non-empty cell, wrapping downward. */ GHOSTTY_SELECTION_ADJUST_RIGHT = 1, /** * Move up one row at the current column, or to the beginning of the * line if already at the top. */ GHOSTTY_SELECTION_ADJUST_UP = 2, /** * 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_DOWN = 3, /** Move to the top-left cell of the screen. */ GHOSTTY_SELECTION_ADJUST_HOME = 4, /** Move to the right edge of the last non-blank row on the screen. */ GHOSTTY_SELECTION_ADJUST_END = 5, /** * Move up by one terminal page height, or to home if that would move * past the top. */ GHOSTTY_SELECTION_ADJUST_PAGE_UP = 6, /** * Move down by one terminal page height, or to end if that would move * past the bottom. */ GHOSTTY_SELECTION_ADJUST_PAGE_DOWN = 7, /** Move to the left edge of the current line. */ GHOSTTY_SELECTION_ADJUST_BEGINNING_OF_LINE = 8, /** Move to the right edge of the current line. */ GHOSTTY_SELECTION_ADJUST_END_OF_LINE = 9, GHOSTTY_SELECTION_ADJUST_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE, } GhosttySelectionAdjust; /** * Selection behavior chosen for a gesture's click sequence. * * @ingroup selection */ typedef enum GHOSTTY_ENUM_TYPED { /** Cell-granular drag selection. */ GHOSTTY_SELECTION_GESTURE_BEHAVIOR_CELL = 0, /** Word selection on press and word-granular drag selection. */ GHOSTTY_SELECTION_GESTURE_BEHAVIOR_WORD = 1, /** Line selection on press and line-granular drag selection. */ GHOSTTY_SELECTION_GESTURE_BEHAVIOR_LINE = 2, /** Semantic command output selection on press and drag. */ GHOSTTY_SELECTION_GESTURE_BEHAVIOR_OUTPUT = 3, GHOSTTY_SELECTION_GESTURE_BEHAVIOR_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE, } GhosttySelectionGestureBehavior; /** * Selection behaviors for single-, double-, and triple-click gestures. * * @ingroup selection */ typedef struct { /** Behavior for single-click selection gestures. */ GhosttySelectionGestureBehavior single_click; /** Behavior for double-click selection gestures. */ GhosttySelectionGestureBehavior double_click; /** Behavior for triple-click selection gestures. */ GhosttySelectionGestureBehavior triple_click; } GhosttySelectionGestureBehaviors; /** * Display geometry used to interpret selection gesture drag events. * * @ingroup selection */ typedef struct { /** Number of columns in the rendered terminal grid. Must be non-zero. */ uint32_t columns; /** Width of one terminal cell in surface pixels. Must be non-zero. */ uint32_t cell_width; /** Left padding before the terminal grid begins in surface pixels. */ uint32_t padding_left; /** Height of the rendered terminal surface in surface pixels. Must be non-zero. */ uint32_t screen_height; } GhosttySelectionGestureGeometry; /** * Current autoscroll direction for an active selection drag gesture. * * @ingroup selection */ typedef enum GHOSTTY_ENUM_TYPED { /** No selection autoscroll is requested. */ GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_NONE = 0, /** Selection dragging should autoscroll the viewport upward. */ GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_UP = 1, /** Selection dragging should autoscroll the viewport downward. */ GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_DOWN = 2, GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE, } GhosttySelectionGestureAutoscroll; /** * Data fields readable from a selection gesture with * ghostty_selection_gesture_get(). * * @ingroup selection */ typedef enum GHOSTTY_ENUM_TYPED { /** Current click count: uint8_t*. 0 means inactive. */ GHOSTTY_SELECTION_GESTURE_DATA_CLICK_COUNT = 0, /** Whether the current/last left-click gesture has dragged: bool*. */ GHOSTTY_SELECTION_GESTURE_DATA_DRAGGED = 1, /** Current autoscroll request: GhosttySelectionGestureAutoscroll*. */ GHOSTTY_SELECTION_GESTURE_DATA_AUTOSCROLL = 2, /** Current gesture behavior: GhosttySelectionGestureBehavior*. */ GHOSTTY_SELECTION_GESTURE_DATA_BEHAVIOR = 3, /** * 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. */ GHOSTTY_SELECTION_GESTURE_DATA_ANCHOR = 4, GHOSTTY_SELECTION_GESTURE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE, } GhosttySelectionGestureData; /** * 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. * * @ingroup selection */ typedef enum GHOSTTY_ENUM_TYPED { /** Press event for ghostty_selection_gesture_event(). */ GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS = 0, /** Release event for ghostty_selection_gesture_event(). */ GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE = 1, /** Drag event for ghostty_selection_gesture_event(). */ GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG = 2, /** Autoscroll tick event for ghostty_selection_gesture_event(). */ GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_AUTOSCROLL_TICK = 3, /** Deep press event for ghostty_selection_gesture_event(). */ GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS = 4, GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE, } GhosttySelectionGestureEventType; /** * Options stored on a reusable selection gesture event. * * Passing NULL as the value to ghostty_selection_gesture_event_set() clears the * corresponding option. * * @ingroup selection */ typedef enum GHOSTTY_ENUM_TYPED { /** * 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_REF = 0, /** * Surface-space pointer position: GhosttySurfacePosition*. * * Valid for PRESS, DRAG, and AUTOSCROLL_TICK. */ GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION = 1, /** Maximum repeat-click distance in pixels: double*. */ GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_DISTANCE = 2, /** * 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_TIME_NS = 3, /** Maximum interval between repeat clicks in nanoseconds: uint64_t*. */ GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_INTERVAL_NS = 4, /** * 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_WORD_BOUNDARY_CODEPOINTS = 5, /** * Selection behavior table: GhosttySelectionGestureBehaviors*. * * If unset, press uses the default behavior table: cell, word, line.