pub struct TrackedGridRef { /* private fields */ }Expand description
Owned grid references that move with the terminal.
A tracked grid reference follows its cell across normal screen operations. For example scrolling, scrollback pruning, resize/reflow, and other terminal mutations update the tracked reference automatically.
A tracked reference can still lose its original semantic location.
This can happen when the underlying grid is reset, pruned, or otherwise
discarded in a way that cannot be mapped to a meaningful new cell.
In that state, TrackedGridRef::has_value returns false and
TrackedGridRef::snapshot / TrackedGridRef::point return Ok(None).
The handle remains valid, and callers may move it to a new point with
TrackedGridRef::set.
To read cell data from a tracked reference, first snapshot it with
TrackedGridRef::snapshot. The returned GridRef is again an
untracked reference and follows the same short lifetime rules as any
other untracked grid reference.
A tracked reference belongs to the terminal screen/page-list that was
active when it was created or last set. Converting it to a point uses that
owning screen/page-list, even if the terminal has since switched between
primary and alternate screens. Calling TrackedGridRef::set resolves
the new point against the terminal’s currently active screen/page-list
and may move the tracked reference between screens.
If the tracked grid reference outlives the terminal it is created from,
it remains valid, but all APIs return either false or Ok(None).
Each tracked reference adds bookkeeping to terminal mutations. Use them sparingly for long-lived anchors such as selections, search state, marks, or application-side bookmarks.
Implementations§
Source§impl TrackedGridRef
impl TrackedGridRef
Sourcepub fn has_value(&self) -> bool
pub fn has_value(&self) -> bool
Whether a tracked grid reference currently has a meaningful value.
If the terminal that created the tracked reference has been dropped, this returns false.
Sourcepub fn snapshot<'t>(
&self,
terminal: &'t Terminal<'_, '_>,
) -> Result<Option<GridRef<'t>>>
pub fn snapshot<'t>( &self, terminal: &'t Terminal<'_, '_>, ) -> Result<Option<GridRef<'t>>>
Snapshot a tracked grid reference into a regular GridRef.
The returned GridRef is an untracked snapshot and has the same lifetime
rules as Terminal::grid_ref: it is only valid until the next terminal update.
Snapshot immediately before calling GridRef::cell, GridRef::row,
GridRef::graphemes, GridRef::hyperlink_uri, or GridRef::style,
If the tracked reference no longer has a meaningful value, this returns
Ok(None). This includes references whose owning terminal has been dropped.
Sourcepub fn point(&self, space: PointSpace) -> Result<Option<PointCoordinate>>
pub fn point(&self, space: PointSpace) -> Result<Option<PointCoordinate>>
Convert a tracked grid reference to a point in the requested coordinate space.
This is the tracked equivalent of Terminal::point_from_grid_ref.
Unlike snapshotting, this does not expose an intermediate untracked
GridRef.
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
Ok(None). Ok(None 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 dropped.
Sourcepub fn set(
&mut self,
terminal: &mut Terminal<'_, '_>,
point: Point,
) -> Result<&mut Self>
pub fn set( &mut self, terminal: &mut Terminal<'_, '_>, point: Point, ) -> Result<&mut Self>
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 Err(Error::OutOfMemory), 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.