Selection

Select words, lines, and ranges, and turn pointer gestures into selections. More...

Detailed Description

Select words, lines, and ranges, and turn pointer gestures into selections.

A selection is a range of terminal content between two cells. It is a snapshot, only valid until the next change to the terminal.

You need a terminal, and usually a grid reference to start from.

Example

GhosttyTerminalSelectWordOptions word =
    GHOSTTY_INIT_SIZED(GhosttyTerminalSelectWordOptions);
word.ref = ref;
 
GhosttySelection selection = {0};
if (ghostty_terminal_select_word(terminal, &word, &selection) ==
    GHOSTTY_SUCCESS) {
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_SELECTION, &selection);
}

Full program: c-vt-selection/src/main.c

The Selection guide covers making one, turning pointer gestures into one, and copying it out.

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_INVALID = 0 , GHOSTTY_SELECTION_GESTURE_DATA_CLICK_COUNT = 1 , GHOSTTY_SELECTION_GESTURE_DATA_DRAGGED = 2 , GHOSTTY_SELECTION_GESTURE_DATA_AUTOSCROLL = 3 ,   GHOSTTY_SELECTION_GESTURE_DATA_BEHAVIOR = 4 , GHOSTTY_SELECTION_GESTURE_DATA_ANCHOR = 5 , 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_INVALID = 0 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF = 1 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION = 2 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_DISTANCE = 3 ,   GHOSTTY_SELECTION_GESTURE_EVENT_OPT_TIME_NS = 4 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_INTERVAL_NS = 5 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_WORD_BOUNDARY_CODEPOINTS = 6 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_BEHAVIORS = 7 ,   GHOSTTY_SELECTION_GESTURE_EVENT_OPT_RECTANGLE = 8 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY = 9 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_VIEWPORT = 10 , GHOSTTY_SELECTION_GESTURE_EVENT_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }

Data Structures
struct	GhosttySelection
struct	GhosttySelectionBuffer
struct	GhosttyTerminalSelectWordOptions
struct	GhosttyTerminalSelectWordBetweenOptions
struct	GhosttyTerminalSelectLineOptions
struct	GhosttySelectionGestureBehaviors
struct	GhosttySelectionGestureGeometry
struct	GhosttySurfacePosition

Gesture Events
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)

Gestures
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)

Selecting
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)

Working with Selections
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)

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 60 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 70 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 273 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 380 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 324 of file selection.h.

GhosttySelectionGestureData

enum GhosttySelectionGestureData

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

Enumerator
GHOSTTY_SELECTION_GESTURE_DATA_INVALID	Not a real data type. ghostty_selection_gesture_get() returns GHOSTTY_INVALID_VALUE for it. Its value is 0, so a zeroed or uninitialized variable is never mistaken for a real data type.
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 399 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_INVALID	Not a real option. ghostty_selection_gesture_event_set() returns GHOSTTY_INVALID_VALUE for it. Its value is 0, so a zeroed or uninitialized variable is never mistaken for a real option.
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 466 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 439 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 248 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.

An autoscroll tick scrolls the viewport exactly one row in the direction GHOSTTY_SELECTION_GESTURE_DATA_AUTOSCROLL reports, then continues the drag at the viewport coordinate. The gesture has no timer of its own. While that direction is up or down, send ticks from a timer you run. The interval is up to you, and ticking faster scrolls faster. A tick returns GHOSTTY_NO_VALUE and scrolls nothing if there's no direction to scroll in. If the cell of the original press is no longer on the active screen, it also resets the gesture and leaves any existing terminal selection alone, so stop your timer.

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

allocator	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, GHOSTTY_INVALID_VALUE if event or value is invalid, or GHOSTTY_UNSUPPORTED if option is not known to this version of the library

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, GHOSTTY_INVALID_VALUE if gesture, Terminal, or out is invalid, or GHOSTTY_UNSUPPORTED if data is not known to this version of the library

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.

Use this when each call into the library is expensive, for example from WebAssembly or from another language through its foreign function interface. It reads every key in one call. From C in the same process it costs the same as calling ghostty_selection_gesture_get() once per key, so use whichever reads better.

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 if every key succeeds. Otherwise the result of the first key that failed, for example GHOSTTY_UNSUPPORTED for a key that is not known to this version of the library.

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

allocator	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.

Examples

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

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.

Examples

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

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.

Examples

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

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.

Examples

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

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 = {0};
  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 = {0};
  result = ghostty_terminal_select_word_between(
      terminal, &end_word_opts, &end_word);
  assert(result == GHOSTTY_SUCCESS);
 
  GhosttySelection drag_selection = {0};
  drag_selection.start = start_word.start;
  drag_selection.end = end_word.end;
  print_selection(terminal, "double-click drag", &drag_selection);

Full program: c-vt-selection/src/main.c

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.

Examples

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

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 your 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_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.