mirrors/ghostty
1
0
Fork 0
mirror of https://github.com/ghostty-org/ghostty.git synced 2026-05-25 06:18:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

libghostty: document selection snapshot lifetime

Browse Source 
Clarify that GhosttySelection is a snapshot type whose endpoints are
untracked GhosttyGridRef values. The previous documentation described the
range shape but did not repeat the grid reference lifetime caveat, which
made it easy to keep selections across terminal mutations incorrectly.
This commit is contained in:
Mitchell Hashimoto
2026-05-23 15:04:51 -07:00
parent 24048ffd47
commit 545a5aef66
1 changed files with 39 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
include/ghostty/vt/selection.h
View File

@@ -17,14 +17,34 @@ extern "C" {
/** @defgroup selection Selection
*
* A selection range defined by two grid references that identifies a
* contiguous or rectangular region of terminal content.
* 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.
*
* @{
*/
/**
* A selection range defined by two grid references.
* 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.
*
@@ -34,13 +54,26 @@ typedef struct {
/** Size of this struct in bytes. Must be set to sizeof(GhosttySelection). */
size_t size;
/** Start of the selection range (inclusive). */
/**
* 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). */
/**
* 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 selection is rectangular (block) rather than linear. */
/**
* Whether the endpoints are interpreted as a rectangular/block selection
* rather than a linear selection.
*/
bool rectangle;
} GhosttySelection;