1/**
2 * @file grid_ref_tracked.h
3 *
4 * Tracked terminal grid references.
5 */
6
7#ifndef GHOSTTY_VT_GRID_REF_TRACKED_H
8#define GHOSTTY_VT_GRID_REF_TRACKED_H
9
10#include <stdbool.h>
11#include <ghostty/vt/types.h>
12#include <ghostty/vt/grid_ref.h>
13#include <ghostty/vt/point.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19/**
20 * Tracked grid references are owned grid references that move with the
21 * terminal. See @ref grid_ref for the full overview of tracked and untracked
22 * grid reference behavior.
23 *
24 * @ingroup grid_ref
25 */
26
27/**
28 * Free a tracked grid reference.
29 *
30 * Passing NULL is allowed and has no effect. A tracked reference may be freed
31 * after the terminal that created it is freed.
32 *
33 * @param ref Tracked grid reference to free.
34 *
35 * @ingroup grid_ref
36 */
37GHOSTTY_API void ghostty_tracked_grid_ref_free(GhosttyTrackedGridRef ref);
38
39/**
40 * Return whether a tracked grid reference currently has a meaningful value.
41 *
42 * If the terminal that created the tracked reference has been freed, this
43 * returns false.
44 *
45 * @param ref Tracked grid reference.
46 * @return true if the reference currently has a meaningful value.
47 *
48 * @ingroup grid_ref
49 */
50GHOSTTY_API bool ghostty_tracked_grid_ref_has_value(
51 GhosttyTrackedGridRef ref);
52
53/**
54 * Convert a tracked grid reference to a point in the requested coordinate
55 * space.
56 *
57 * This is the tracked equivalent of ghostty_terminal_point_from_grid_ref().
58 * Unlike snapshotting, this does not expose an intermediate untracked
59 * GhosttyGridRef.
60 *
61 * A tracked reference is resolved against the terminal screen/page-list that
62 * currently owns the reference. If the terminal has switched between primary
63 * and alternate screens since the reference was created or last set, this may
64 * be different from the terminal's currently active screen.
65 *
66 * If the tracked reference no longer has a meaningful value, this returns
67 * GHOSTTY_NO_VALUE. GHOSTTY_NO_VALUE is also returned when the reference cannot
68 * be represented in the requested coordinate space, including after the
69 * terminal that created the tracked reference has been freed.
70 *
71 * @param ref Tracked grid reference.
72 * @param tag Coordinate space to convert into.
73 * @param[out] out_point On success, receives the coordinate. May be NULL.
74 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref is invalid,
75 * or GHOSTTY_NO_VALUE if there is no representable value.
76 *
77 * @ingroup grid_ref
78 */
79GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_point(
80 GhosttyTrackedGridRef ref,
81 GhosttyPointTag tag,
82 GhosttyPointCoordinate *out_point);
83
84/**
85 * Move an existing tracked grid reference to a new terminal point.
86 *
87 * On success, the tracked reference begins tracking the new point and any prior
88 * "no value" state is cleared. On GHOSTTY_OUT_OF_MEMORY, the original tracked
89 * reference is left unchanged.
90 *
91 * The terminal must be the same terminal that created the tracked reference.
92 * The point is resolved against the terminal screen/page-list that is active at
93 * the time this function is called. If the terminal has switched between
94 * primary and alternate screens, this may move the tracked reference from one
95 * screen/page-list to the other.
96 *
97 * @param ref Tracked grid reference.
98 * @param terminal Terminal instance that owns the reference.
99 * @param point New point to track.
100 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref, terminal,
101 * or point is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation fails.
102 *
103 * @ingroup grid_ref
104 */
105GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_set(
106 GhosttyTrackedGridRef ref,
107 GhosttyTerminal terminal,
108 GhosttyPoint point);
109
110/**
111 * Snapshot a tracked grid reference into a regular GhosttyGridRef.
112 *
113 * The returned GhosttyGridRef is an untracked snapshot and has the same
114 * lifetime rules as ghostty_terminal_grid_ref(): it is only valid until the
115 * next terminal update. Snapshot immediately before calling
116 * ghostty_grid_ref_cell(), ghostty_grid_ref_row(),
117 * ghostty_grid_ref_graphemes(), ghostty_grid_ref_hyperlink_uri(), or
118 * ghostty_grid_ref_style().
119 *
120 * If the tracked reference no longer has a meaningful value, this returns
121 * GHOSTTY_NO_VALUE. This includes references whose owning terminal has been
122 * freed.
123 *
124 * @param ref Tracked grid reference.
125 * @param[out] out_ref On success, receives an untracked snapshot. May be NULL.
126 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref is invalid,
127 * or GHOSTTY_NO_VALUE if the tracked location was discarded.
128 *
129 * @ingroup grid_ref
130 */
131GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_snapshot(
132 GhosttyTrackedGridRef ref,
133 GhosttyGridRef *out_ref);
134
135#ifdef __cplusplus
136}
137#endif
138
139#endif /* GHOSTTY_VT_GRID_REF_TRACKED_H */