TextPointer Class

Reference

Definition

Namespace:: System.Windows.Documents

Assembly:: PresentationFramework.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Represents a position within a FlowDocument or TextBlock.

public ref class TextPointer : System::Windows::Documents::ContentPosition

public class TextPointer : System.Windows.Documents.ContentPosition

type TextPointer = class
    inherit ContentPosition

Public Class TextPointer
Inherits ContentPosition

Inheritance: Object

ContentPosition
TextPointer

Examples

The following example demonstrates how to use a TextPointer to find a position just inside of the first Run element in a specified text container.

// This method returns the position just inside of the first text Run (if any) in a 
// specified text container.
TextPointer FindFirstRunInTextContainer(DependencyObject container)
{
    TextPointer position = null;

    if (container != null){
        if (container is FlowDocument)
            position = ((FlowDocument)container).ContentStart;
        else if (container is TextBlock)
            position = ((TextBlock)container).ContentStart;
        else
            return position;
    }
    // Traverse content in forward direction until the position is immediately after the opening 
    // tag of a Run element, or the end of content is encountered.
    while (position != null)
    {
        // Is the current position just after an opening element tag?
        if (position.GetPointerContext(LogicalDirection.Backward) == TextPointerContext.ElementStart)
        {
            // If so, is the tag a Run?
            if (position.Parent is Run)
                break;
        }

        // Not what we're looking for; on to the next position.
        position = position.GetNextContextPosition(LogicalDirection.Forward);
    }
        
    // This will be either null if no Run is found, or a position just inside of the first Run element in the
    // specifed text container.  Because position is formed from ContentStart, it will have a logical direction
    // of Backward.
    return position;
}

' This method returns the position just inside of the first text Run (if any) in a 
' specified text container.
Private Function FindFirstRunInTextContainer(ByVal container As DependencyObject) As TextPointer
    Dim position As TextPointer = Nothing

    If container IsNot Nothing Then
        If TypeOf container Is FlowDocument Then
            position = (CType(container, FlowDocument)).ContentStart
        ElseIf TypeOf container Is TextBlock Then
            position = (CType(container, TextBlock)).ContentStart
        Else
            Return position
        End If
    End If
    ' Traverse content in forward direction until the position is immediately after the opening 
    ' tag of a Run element, or the end of content is encountered.
    Do While position IsNot Nothing
        ' Is the current position just after an opening element tag?
        If position.GetPointerContext(LogicalDirection.Backward) = TextPointerContext.ElementStart Then
            ' If so, is the tag a Run?
            If TypeOf position.Parent Is Run Then
                Exit Do
            End If
        End If

        ' Not what we're looking for on to the next position.
        position = position.GetNextContextPosition(LogicalDirection.Forward)
    Loop

    ' This will be either null if no Run is found, or a position just inside of the first Run element in the
    ' specifed text container.  Because position is formed from ContentStart, it will have a logical direction
    ' of Backward.
    Return position
End Function

The following example implements a simplistic find algorithm using TextPointer facilities.

// This method will search for a specified word (string) starting at a specified position.
TextPointer FindWordFromPosition(TextPointer position, string word)
{
    while (position != null)
    {
         if (position.GetPointerContext(LogicalDirection.Forward) == TextPointerContext.Text)
         {
             string textRun = position.GetTextInRun(LogicalDirection.Forward);

             // Find the starting index of any substring that matches "word".
             int indexInRun = textRun.IndexOf(word);
             if (indexInRun >= 0)
             {
                 position = position.GetPositionAtOffset(indexInRun);
                 break;
             }
         }
         else
        {
            position = position.GetNextContextPosition(LogicalDirection.Forward);
        }
    }

     // position will be null if "word" is not found.
     return position; 
}

' This method will search for a specified word (string) starting at a specified position.
Private Function FindWordFromPosition(ByVal position As TextPointer, ByVal word As String) As TextPointer
    Do While position IsNot Nothing
        If position.GetPointerContext(LogicalDirection.Forward) = TextPointerContext.Text Then
            Dim textRun As String = position.GetTextInRun(LogicalDirection.Forward)

            ' Find the starting index of any substring that matches "word".
            Dim indexInRun As Integer = textRun.IndexOf(word)
            If indexInRun >= 0 Then
                position = position.GetPositionAtOffset(indexInRun)
                Exit Do
            End If
        Else
            position = position.GetNextContextPosition(LogicalDirection.Forward)
        End If
    Loop

    ' position will be null if "word" is not found.
    Return position
End Function

Remarks

The TextPointer class introduces the following terminology:

Position - Inherently, a TextPointer always points to a position in content. Such positions either fall between characters in the content, or between flow content element tags that define structure for the content.
Current Position - Because a TextPointer always indicates a position, and because many of the operations that can be performed through a TextPointer are relative to the position currently pointed to by the TextPointer, it makes sense to simply refer to the position indicated by a TextPointer as the current position.
Insertion Position - An insertion position is a position where new content may be added without breaking any semantic rules for the associated content. In practice, an insertion position is anywhere in content where a caret may be positioned. An example of a valid TextPointer position that is not an insertion position is the position between two adjacent Paragraph tags (that is, between the closing tag of the preceding paragraph and the opening tag of the next paragraph).
Symbol - For the purposes of TextPointer operations that involve symbols, any of the following is considered to be a symbol:
- An opening or closing tag for a TextElement element.
- A UIElement element contained within an InlineUIContainer or BlockUIContainer. Note that such a UIElement is always counted as exactly one symbol; any additional content or elements contained by the UIElement are not counted as symbols.
- Each 16-bit Unicode character inside of a text Run element.
Text Container - A text container is the element that forms the ultimate border for the flow content at hand; the position indicated by a TextPointer always falls within a text container. Currently, a text container must be either a FlowDocument or a TextBlock. Generally speaking, operations between TextPointer instances in different text containers are not supported.
Document - The content in a text container is referred to as a document, as in the IsInSameDocument method and the DocumentStart and DocumentEnd properties.

The TextPointer class is intended to facilitate traversal and manipulation of content that is represented by Windows Presentation Foundation (WPF) flow content elements; in general, such elements derive from TextElement. Some of the operations that TextPointer facilitates include the following:

Perform an ordinal comparison of the current position with a second specified position. See the CompareTo method.
Determine the type of content adjacent to the current position in a specified direction. See the GetPointerContext method and TextPointerContext enumeration.
Get the TextElement that scopes or is adjacent to the current position. See Paragraph and the GetAdjacentElement method.
Get the text container that scopes the current document. See the Parent property.
Get a specified number of characters preceding or following the current position. See the GetTextInRun method.
Insert a string of characters at the current position. See the InsertTextInRun method.
Find line boundaries in content. See the GetLineStartPosition method and IsAtLineStartPosition property.
Translate between TextPointer positions and symbol offsets into content. See the GetOffsetToPosition and GetPositionAtOffset methods.
Perform visual hit testing by translating between a TextPointer position and a Point representing relative coordinates.
Find a nearby insertion position, or check whether the current position is an insertion position. See the GetInsertionPosition and GetNextInsertionPosition methods and the IsAtInsertionPosition property.

The position and LogicalDirection indicated by a TextPointer object are immutable. When content is edited or modified, the position indicated by a TextPointer does not change relative to the surrounding text; rather the offset of that position from the beginning of content is adjusted correspondingly to reflect the new relative position in content. For example, a TextPointer that indicates a position at the beginning of a given paragraph continues to point to the beginning of that paragraph even when content is inserted or deleted before or after the paragraph.

The TextPointer class does not provide any public constructors. An instance of TextPointer is created by using properties or methods of other objects (including other TextPointer objects). The following list provides a few examples of methods and properties that create and return a TextPointer. This list is not exhaustive:

From a TextRange: Start and End.
From a TextElement: ContentStart, ContentEnd, ElementStart, and ElementEnd.
From a TextBlock (text container): ContentStart, ContentEnd, and GetPositionFromPoint.
From a FlowDocument (text container): ContentStart, and ContentEnd
From an existing TextPointer: DocumentStart, DocumentEnd, GetNextInsertionPosition, and GetPositionAtOffset.

Properties

DocumentEnd	Gets a TextPointer at the end of content in the text container associated with the current position.
DocumentStart	Gets a TextPointer at the beginning of content in the text container associated with the current position.
HasValidLayout	Gets a value that indicates whether the text container associated with the current position has a valid (up-to-date) layout.
IsAtInsertionPosition	Gets a value that indicates whether the current position is an insertion position.
IsAtLineStartPosition	Gets a value that indicates whether the current position is at the beginning of a line.
LogicalDirection	Gets the logical direction associated with the current position which is used to disambiguate content associated with the current position.
Paragraph	Gets the paragraph that scopes the current position, if any.
Parent	Gets the logical parent that scopes the current position.

Methods

CompareTo(TextPointer)	Performs an ordinal comparison between the positions specified by the current TextPointer and a second specified TextPointer.
DeleteTextInRun(Int32)	Deletes the specified number of characters from the position indicated by the current TextPointer.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetAdjacentElement(LogicalDirection)	Returns the element, if any, that borders the current TextPointer in the specified logical direction.
GetCharacterRect(LogicalDirection)	Returns a bounding box (Rect) for content that borders the current TextPointer in the specified logical direction.
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetInsertionPosition(LogicalDirection)	Returns a TextPointer to the closest insertion position in the specified logical direction.
GetLineStartPosition(Int32)	Returns a TextPointer to the beginning of a line that is specified relative to the current TextPointer.
GetLineStartPosition(Int32, Int32)	Returns a TextPointer to the beginning of a line that is specified relative to the current TextPointer, and reports how many lines were skipped.
GetNextContextPosition(LogicalDirection)	Returns a pointer to the next symbol in the specified logical direction.
GetNextInsertionPosition(LogicalDirection)	Returns a TextPointer to the next insertion position in the specified logical direction.
GetOffsetToPosition(TextPointer)	Returns the count of symbols between the current TextPointer and a second specified TextPointer.
GetPointerContext(LogicalDirection)	Returns a category indicator for the content adjacent to the current TextPointer in the specified logical direction.
GetPositionAtOffset(Int32)	Returns a TextPointer to the position indicated by the specified offset, in symbols, from the beginning of the current TextPointer.
GetPositionAtOffset(Int32, LogicalDirection)	Returns a TextPointer to the position indicated by the specified offset, in symbols, from the beginning of the current TextPointer and in the specified direction.
GetTextInRun(LogicalDirection)	Returns a string containing any text adjacent to the current TextPointer in the specified logical direction.
GetTextInRun(LogicalDirection, Char[], Int32, Int32)	Copies the specified maximum number of characters from any adjacent text in the specified direction into a caller-supplied character array.
GetTextRunLength(LogicalDirection)	Returns the number of Unicode characters between the current TextPointer and the next non-text symbol, in the specified logical direction.
GetType()	Gets the Type of the current instance. (Inherited from Object)
InsertLineBreak()	Inserts a line break at the current position.
InsertParagraphBreak()	Inserts a paragraph break at the current position.
InsertTextInRun(String)	Inserts the specified text into the text Run at the current position.
IsInSameDocument(TextPointer)	Indicates whether the specified position is in the same text container as the current position.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	This type or member supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used directly from your code.

Applies to

Share via