Grid References

Point at a cell, read it, and keep track of it as the terminal scrolls. More...

Detailed Description

Point at a cell, read it, and keep track of it as the terminal scrolls.

A grid reference points at one cell in the terminal.

An untracked reference is a snapshot that is only valid until the next change to the terminal. A tracked reference follows its cell. Use one to read particular cells. They aren't fast enough to draw a frame, so use Render State for that.

Example

GhosttyGridRef ref = {0};
GhosttyPoint point = {
    .tag = GHOSTTY_POINT_TAG_ACTIVE,
    .value = { .coordinate = { .x = 4, .y = 0 } },
};
 
if (ghostty_terminal_grid_ref(terminal, point, &ref) == GHOSTTY_SUCCESS) {
    GhosttyCell cell;
    ghostty_grid_ref_cell(&ref, &cell);
}

Full program: c-vt-grid-traverse/src/main.c

The Grid guide covers coordinates, both kinds of reference, and when each one dies.

Typedefs
typedef struct GhosttyTrackedGridRefImpl *	GhosttyTrackedGridRef

Functions
GHOSTTY_API GhosttyResult	ghostty_grid_ref_cell (const GhosttyGridRef *ref, GhosttyCell *out_cell)
GHOSTTY_API GhosttyResult	ghostty_grid_ref_row (const GhosttyGridRef *ref, GhosttyRow *out_row)
GHOSTTY_API GhosttyResult	ghostty_grid_ref_graphemes (const GhosttyGridRef *ref, uint32_t *buf, size_t buf_len, size_t *out_written)
GHOSTTY_API GhosttyResult	ghostty_grid_ref_hyperlink_uri (const GhosttyGridRef *ref, uint8_t *buf, size_t buf_len, size_t *out_written)
GHOSTTY_API GhosttyResult	ghostty_grid_ref_style (const GhosttyGridRef *ref, GhosttyStyle *out_style)
GHOSTTY_API void	ghostty_tracked_grid_ref_free (GhosttyTrackedGridRef ref)
GHOSTTY_API bool	ghostty_tracked_grid_ref_has_value (GhosttyTrackedGridRef ref)
GHOSTTY_API GhosttyResult	ghostty_tracked_grid_ref_point (GhosttyTrackedGridRef ref, GhosttyPointTag tag, GhosttyPointCoordinate *out_point)
GHOSTTY_API GhosttyResult	ghostty_tracked_grid_ref_set (GhosttyTrackedGridRef ref, GhosttyTerminal terminal, GhosttyPoint point)
GHOSTTY_API GhosttyResult	ghostty_tracked_grid_ref_snapshot (GhosttyTrackedGridRef ref, GhosttyGridRef *out_ref)

Data Structures
struct	GhosttyGridRef

Typedef Documentation

GhosttyTrackedGridRef

typedef struct GhosttyTrackedGridRefImpl* GhosttyTrackedGridRef

Opaque handle to a tracked grid reference.

A tracked grid reference is owned by you and must be freed with ghostty_tracked_grid_ref_free(). If the terminal that created it is freed first, the handle remains valid only for tracked-grid-ref APIs: it reports no value and can still be freed.

Examples

c-vt-grid-ref-tracked/src/main.c.

Definition at line 215 of file types.h.

Function Documentation

ghostty_grid_ref_cell()

GHOSTTY_API GhosttyResult ghostty_grid_ref_cell	(	const GhosttyGridRef *	ref,
		GhosttyCell *	out_cell )

Get the cell from a grid reference.

Parameters

	ref	Pointer to the grid reference
[out]	out_cell	On success, set to the cell at the ref's position (may be NULL)

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's node is NULL

Examples

c-vt-grid-ref-tracked/src/main.c, and c-vt-grid-traverse/src/main.c.

ghostty_grid_ref_graphemes()

GHOSTTY_API GhosttyResult ghostty_grid_ref_graphemes	(	const GhosttyGridRef *	ref,
		uint32_t *	buf,
		size_t	buf_len,
		size_t *	out_written )

Get the grapheme cluster codepoints for the cell at the grid reference's position.

Writes the full grapheme cluster (the cell's primary codepoint followed by any combining codepoints) into the provided buffer. Both buf_len and out_written count codepoints, not bytes.

If buf is too small, this returns GHOSTTY_OUT_OF_SPACE, sets out_written to the number of codepoints needed, and leaves buf unchanged. To get the count without copying anything, pass NULL for buf and 0 for buf_len. A cell with no text returns GHOSTTY_SUCCESS with out_written set to 0.

Most cells hold a single codepoint, so a small fixed buffer usually works. Fall back to a heap buffer for longer clusters:

uint32_t stack[8];
uint32_t *codepoints = stack;
size_t count = 0;
GhosttyResult result = ghostty_grid_ref_graphemes(&ref, stack, 8, &count);
if (result == GHOSTTY_OUT_OF_SPACE) {
  codepoints = malloc(count * sizeof(uint32_t));
  result = ghostty_grid_ref_graphemes(&ref, codepoints, count, &count);
}
if (result == GHOSTTY_SUCCESS) {
  // codepoints[0] through codepoints[count - 1] hold the cluster
}
if (codepoints != stack) free(codepoints);

Parameters

	ref	Pointer to the grid reference
	buf	Buffer to write the codepoints into. May be NULL if buf_len is 0.
	buf_len	Number of uint32_t elements buf can hold
[out]	out_written	The number of codepoints written, or the number needed if the result is GHOSTTY_OUT_OF_SPACE

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's node is NULL, GHOSTTY_OUT_OF_SPACE if the buffer is too small

ghostty_grid_ref_hyperlink_uri()

GHOSTTY_API GhosttyResult ghostty_grid_ref_hyperlink_uri	(	const GhosttyGridRef *	ref,
		uint8_t *	buf,
		size_t	buf_len,
		size_t *	out_written )

Get the hyperlink URI for the cell at the grid reference's position.

Writes the URI bytes into the provided buffer.

The URI is not NUL-terminated.

If buf is too small, this returns GHOSTTY_OUT_OF_SPACE, sets out_written to the size needed, and leaves buf unchanged. To get the size without copying anything, pass NULL for buf and 0 for buf_len. A cell with no hyperlink returns GHOSTTY_SUCCESS with out_written set to 0.

URIs can be long, so asking for the size first is often simplest:

size_t len = 0;
if (ghostty_grid_ref_hyperlink_uri(&ref, NULL, 0, &len) == GHOSTTY_OUT_OF_SPACE) {
  uint8_t *uri = malloc(len);
  ghostty_grid_ref_hyperlink_uri(&ref, uri, len, &len);
  // uri holds len bytes
  free(uri);
}

Parameters

	ref	Pointer to the grid reference
	buf	Buffer to write the URI into. May be NULL if buf_len is 0.
	buf_len	Size of buf in bytes
[out]	out_written	The number of bytes written, or the size needed if the result is GHOSTTY_OUT_OF_SPACE

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's node is NULL, GHOSTTY_OUT_OF_SPACE if the buffer is too small

ghostty_grid_ref_row()

GHOSTTY_API GhosttyResult ghostty_grid_ref_row	(	const GhosttyGridRef *	ref,
		GhosttyRow *	out_row )

Get the row from a grid reference.

Parameters

	ref	Pointer to the grid reference
[out]	out_row	On success, set to the row at the ref's position (may be NULL)

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's node is NULL

Examples

c-vt-grid-traverse/src/main.c.

ghostty_grid_ref_style()

GHOSTTY_API GhosttyResult ghostty_grid_ref_style	(	const GhosttyGridRef *	ref,
		GhosttyStyle *	out_style )

Get the style of the cell at the grid reference's position.

Parameters

	ref	Pointer to the grid reference
[out]	out_style	On success, set to the cell's style (may be NULL)

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's node is NULL

Examples

c-vt-grid-traverse/src/main.c.

ghostty_tracked_grid_ref_free()

GHOSTTY_API void ghostty_tracked_grid_ref_free

(

GhosttyTrackedGridRef

ref

)

Tracked grid references are owned grid references that move with the terminal. See the Grid guide for how tracked and untracked references behave. Free a tracked grid reference.

Passing NULL is allowed and has no effect. A tracked reference may be freed after the terminal that created it is freed.

Parameters

ref	Tracked grid reference to free.

Examples

c-vt-grid-ref-tracked/src/main.c.

ghostty_tracked_grid_ref_has_value()

GHOSTTY_API bool ghostty_tracked_grid_ref_has_value

(

GhosttyTrackedGridRef

ref

)

Return whether a tracked grid reference currently has a meaningful value.

If the terminal that created the tracked reference has been freed, this returns false.

Parameters

ref	Tracked grid reference.

Returns

true if the reference currently has a meaningful value.

Examples

c-vt-grid-ref-tracked/src/main.c.

ghostty_tracked_grid_ref_point()

GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_point	(	GhosttyTrackedGridRef	ref,
		GhosttyPointTag	tag,
		GhosttyPointCoordinate *	out_point )

Convert a tracked grid reference to a point in the requested coordinate space.

This is the tracked equivalent of ghostty_terminal_point_from_grid_ref(). Unlike snapshotting, this does not expose an intermediate untracked GhosttyGridRef.

A tracked reference is resolved against the terminal screen/page-list that currently owns the reference. If the terminal has switched between primary and alternate screens since the reference was created or last set, this may be different from the terminal's currently active screen.

If the tracked reference no longer has a meaningful value, this returns GHOSTTY_NO_VALUE. GHOSTTY_NO_VALUE is also returned when the reference cannot be represented in the requested coordinate space, including after the terminal that created the tracked reference has been freed.

Parameters

	ref	Tracked grid reference.
	tag	Coordinate space to convert into.
[out]	out_point	On success, receives the coordinate. May be NULL.

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref is invalid, or GHOSTTY_NO_VALUE if there is no representable value.

Examples

c-vt-grid-ref-tracked/src/main.c.

ghostty_tracked_grid_ref_set()

GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_set	(	GhosttyTrackedGridRef	ref,
		GhosttyTerminal	terminal,
		GhosttyPoint	point )

Move an existing tracked grid reference to a new terminal point.

On success, the tracked reference begins tracking the new point and any prior "no value" state is cleared. On GHOSTTY_OUT_OF_MEMORY, the original tracked reference is left unchanged.

The terminal must be the same terminal that created the tracked reference. The point is resolved against the terminal screen/page-list that is active at the time this function is called. If the terminal has switched between primary and alternate screens, this may move the tracked reference from one screen/page-list to the other.

Parameters

ref	Tracked grid reference.
terminal	Terminal instance that owns the reference.
point	New point to track.

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref, terminal, or point is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation fails.

Examples

c-vt-grid-ref-tracked/src/main.c.

ghostty_tracked_grid_ref_snapshot()

GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_snapshot	(	GhosttyTrackedGridRef	ref,
		GhosttyGridRef *	out_ref )

Snapshot a tracked grid reference into a regular GhosttyGridRef.

The returned GhosttyGridRef is an untracked snapshot and has the same lifetime rules as ghostty_terminal_grid_ref(): it is only valid until the next terminal update. Snapshot immediately before calling ghostty_grid_ref_cell(), ghostty_grid_ref_row(), ghostty_grid_ref_graphemes(), ghostty_grid_ref_hyperlink_uri(), or ghostty_grid_ref_style().

If the tracked reference no longer has a meaningful value, this returns GHOSTTY_NO_VALUE. This includes references whose owning terminal has been freed.

Parameters

	ref	Tracked grid reference.
[out]	out_ref	On success, receives an untracked snapshot. May be NULL.

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref is invalid, or GHOSTTY_NO_VALUE if the tracked location was discarded.

Examples

c-vt-grid-ref-tracked/src/main.c.