TextPointer Class
Definition
A position within a document that can be navigated and used for editing. Uses character offsets (not symbols) for simplicity.
public class TextPointer
Remarks
Performance optimization: Caches only the leaf node instead of the full path, reducing allocations from 320-656 B to ~40-80 B per pointer. The full path is lazy-loaded only when explicitly accessed (rare).
Mutability and aliasing. A Avalonia.Controls.Documents.TextModel.TextPointer is a
mutable, tracked position: Avalonia.Controls.Documents.TextModel.TextPointer.UpdateInPlace(int) and
Avalonia.Controls.Documents.TextModel.TextPointer.Refresh change Avalonia.Controls.Documents.TextModel.TextPointer.Offset and the cached leaf
in place. APIs that return a freshly allocated pointer
(Avalonia.Controls.Documents.TextModel.TextDocument.CreatePointer(int,Avalonia.Controls.Documents.TextModel.LogicalDirection),
CreatePointerAtNodeStart/End, Avalonia.Controls.Documents.TextModel.TextPointer.GetPositionAtOffset(int,Avalonia.Controls.Documents.TextModel.LogicalDirection))
may be stored directly in mutable containers. APIs that return a
cached pointer (Avalonia.Controls.Documents.TextModel.TextDocument.ContentStart/
Avalonia.Controls.Documents.TextModel.TextDocument.ContentEnd,
Avalonia.Controls.Documents.RichTextElement.ContentStart/
Avalonia.Controls.Documents.RichTextElement.ContentEnd) hand back a shared instance;
callers that need an independent tracked position must call
Avalonia.Controls.Documents.TextModel.TextPointer.Clone first. Avalonia.Controls.Documents.TextModel.TextRange performs this
clone automatically for its endpoints.
Methods
| Name | Description |
|---|---|
| Clone | Creates a detached copy of this pointer that will not be mutated by subsequent UpdateInPlace or Avalonia.Controls.Documents.TextModel.TextPointer.Refresh calls on the original. The clone preserves node identity so that callers storing the pointer (e.g. undo snapshots) can use the cached leaf as a disambiguation key across document edits. |
| CompareTo | Compares the document position of this pointer to other. |
| CreatePointer | Creates a fresh, independent Avalonia.Controls.Documents.TextModel.TextPointer at the document-absolute offset absoluteOffset. |
| EnsureElement | Materializes and returns the element at this pointer's leaf node. |
| EnsureParentElement | Materializes and returns the element at the immediate parent node. |
| GetContainingElement | Gets the containing element, materializing the leaf and its ancestors on demand until a Avalonia.Controls.Documents.RichTextElement is available. Returns null only when the document is empty. |
| GetOffsetToPosition | Gets the distance from this pointer to another. |
| GetPositionAtOffset | Gets a pointer at the specified offset from this position. |
| InsertText (2 overloads) | No summary available. |
| Refresh | Refreshes this pointer if stale. |
| ToString | No summary available. |
Clone Method
Creates a detached copy of this pointer that will not be mutated
by subsequent UpdateInPlace or Avalonia.Controls.Documents.TextModel.TextPointer.Refresh
calls on the original. The clone preserves node identity so that
callers storing the pointer (e.g. undo snapshots) can use the
cached leaf as a disambiguation key across document edits.
public Avalonia.Controls.Documents.TextModel.TextPointer Clone()
Returns
Avalonia.Controls.Documents.TextModel.TextPointer
A pointer at the same position, independent of this one.
Remarks
Required when assigning a cached pointer
(Avalonia.Controls.Documents.TextModel.TextDocument.ContentStart, Avalonia.Controls.Documents.TextModel.TextDocument.ContentEnd,
Avalonia.Controls.Documents.RichTextElement.ContentStart,
Avalonia.Controls.Documents.RichTextElement.ContentEnd)
into any container that may later mutate the pointer via
Avalonia.Controls.Documents.TextModel.TextPointer.Refresh. Without cloning, those mutations leak
through the alias and shift the source cache. Avalonia.Controls.Documents.TextModel.TextRange's
constructors and SetPositions already perform this clone.
Exceptions
CompareTo Method
Compares the document position of this pointer to other.
public int CompareTo(Avalonia.Controls.Documents.TextModel.TextPointer other)
Parameters
other Avalonia.Controls.Documents.TextModel.TextPointer
Returns
int
CreatePointer Method
Creates a fresh, independent Avalonia.Controls.Documents.TextModel.TextPointer at the
document-absolute offset absoluteOffset.
public Avalonia.Controls.Documents.TextModel.TextPointer CreatePointer(int absoluteOffset, Avalonia.Controls.Documents.TextModel.LogicalDirection direction)
Parameters
absoluteOffset int
direction Avalonia.Controls.Documents.TextModel.LogicalDirection
Returns
Avalonia.Controls.Documents.TextModel.TextPointer
Remarks
The result is identical to what an offset-based factory rooted at
the document would produce — the receiver pointer is a performance
hint only, not a structural anchor. When
absoluteOffset is strictly interior to one of
this pointer's ancestors the descent is localized to that
subtree; at boundary offsets it falls through to a full root
descent so the result is provably equivalent.
The offset is clamped to [0, doc.Length].
This method is the absolute-offset companion to Avalonia.Controls.Documents.TextModel.TextPointer.GetPositionAtOffset(int,Avalonia.Controls.Documents.TextModel.LogicalDirection), which is intentionally hint-biased for navigation (a relative offset of 0 with a boundary-anchored pointer stays in the source block; the same absolute offset through this method does not).
Exceptions
EnsureElement Method
Materializes and returns the element at this pointer's leaf node.
public Avalonia.Controls.Documents.RichTextElement EnsureElement()
Returns
EnsureParentElement Method
Materializes and returns the element at the immediate parent node.
public Avalonia.Controls.Documents.RichTextElement EnsureParentElement()
Returns
GetContainingElement Method
Gets the containing element, materializing the leaf and its
ancestors on demand until a Avalonia.Controls.Documents.RichTextElement is
available. Returns null only when the document is empty.
public Avalonia.Controls.Documents.RichTextElement GetContainingElement()
Returns
GetOffsetToPosition Method
Gets the distance from this pointer to another.
public int GetOffsetToPosition(Avalonia.Controls.Documents.TextModel.TextPointer other)
Parameters
other Avalonia.Controls.Documents.TextModel.TextPointer
Returns
int
GetPositionAtOffset Method
Gets a pointer at the specified offset from this position.
public Avalonia.Controls.Documents.TextModel.TextPointer GetPositionAtOffset(int relativeOffset, Avalonia.Controls.Documents.TextModel.LogicalDirection direction)
Parameters
relativeOffset int
direction Avalonia.Controls.Documents.TextModel.LogicalDirection
Returns
Avalonia.Controls.Documents.TextModel.TextPointer
Remarks
The result is clamped to [0, doc.Length]: passing an
offset that would land before 0 returns a pointer at
0; passing one beyond doc.Length returns a
pointer at the document end. This matches the behavior of the
underlying leaf-resolution primitives and avoids forcing every
caller through a redundant null-check after navigation.
To detect "I navigated past the document edge", compare offsets
explicitly (this.Offset + relative != result.Offset or
the simpler this.Offset == 0 / this.Offset == doc.Length
pre-check), rather than checking for null.
When the target offset falls within the same parent node as this pointer's cached leaf (the common case for paragraph-local operations), the tree walk is bounded to the subtree instead of traversing from the root. This eliminates per-call O(depth) overhead for hit-testing and line queries inside a single paragraph.
Exceptions
InsertText overloads
InsertText Method
public Avalonia.Controls.Documents.TextModel.TextPointer InsertText(ReadOnlyMemory<char> text)
Parameters
text ReadOnlyMemory<char>
Returns
InsertText Method
Inserts text at this position.
public Avalonia.Controls.Documents.TextModel.TextPointer InsertText(string text)
Parameters
text string
Returns
Refresh Method
Refreshes this pointer if stale.
public void Refresh()
ToString Method
public string ToString()
Returns
string
Properties
| Name | Description |
|---|---|
| Element | The element at this position, if already realized. May be null when the underlying node still holds only a deferred snapshot. Use Avalonia.Controls.Documents.TextModel.TextPointer.EnsureElement to force materialization. |
| IsStale | Whether this pointer is stale (document has changed since creation). |
| LogicalDirection | The logical direction (gravity) of this pointer. |
| Offset | The character offset in the document. |
| TextDocument | The document this pointer belongs to. |
Element Property
The element at this position, if already realized. May be null
when the underlying node still holds only a deferred snapshot.
Use Avalonia.Controls.Documents.TextModel.TextPointer.EnsureElement to force materialization.
public Avalonia.Controls.Documents.RichTextElement Element { get; set; }
IsStale Property
Whether this pointer is stale (document has changed since creation).
public bool IsStale { get; set; }
LogicalDirection Property
The logical direction (gravity) of this pointer.
public Avalonia.Controls.Documents.TextModel.LogicalDirection LogicalDirection { get; set; }
Offset Property
The character offset in the document.
public int Offset { get; set; }
TextDocument Property
The document this pointer belongs to.
public Avalonia.Controls.Documents.TextModel.TextDocument TextDocument { get; set; }