This documentation is archived and is not being maintained.

TextPointer.GetInsertionPosition Method

Returns a TextPointer to the closest insertion position in the specified logical direction.

Namespace:  System.Windows.Documents
Assembly:  PresentationFramework (in PresentationFramework.dll)

public TextPointer GetInsertionPosition(
	LogicalDirection direction


Type: System.Windows.Documents.LogicalDirection
One of the LogicalDirection values that specifies the logical direction in which to search for the closest insertion position.

Return Value

Type: System.Windows.Documents.TextPointer
A TextPointer to the closest insertion position in the specified direction.

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).

If the TextPointer already points to a valid insertion position, but the closing tag for a non-empty formatting sequence directly follows that position in the given direction, then the TextPointer returned by this method is adjusted to point to the insertion position just after the close of the formatting sequence. For example, consider the markup sequence <Bold>a</Bold>b. Note that there are two insertion positions between the letters a and b—one that precedes the closing Bold tag, and one directly following the closing Bold tag. If GetInsertionPosition is called on a TextPointer to the position directly after the letter a and before of the closing Bold tag, and with a direction of Forward, the returned TextPointer is adjusted to point to the position just before the letter b, after the closing Bold tag. A similar adjustment is made for opening formatting tags when working in the opposite logical direction. This method is intended to provide a means of disambiguation between insertion positions in similar cases.

This method can also be used to be selective about insertion points when a sequence of structural tags is involved. For example, when at a position between closing and opening paragraph tags, the direction parameter can be used to select the closest insertion point at the beginning of the following paragraph (by specifying LogicalDirection.Forward) or at the end of the preceding paragraph (by specifying LogicalDirection.Backward).

If the pointer is already at insertion position, and there are no adjacent formatting tags in the specified direction, the returned TextPointer points to the same position as the calling TextPointer.

It is possible that no valid insertion position exists relative to the position pointed to by a TextPointer. This can happen if the referenced content is structurally incomplete, as in an empty table or list. In such cases, this method simply returns a TextPointer to the same position as the TextPointer from which this method was called. This method always returns a valid TextPointer.

This example shows how to use the GetInsertionPosition method to check whether a specified TextElement is empty of printable content.

// Tests to see if the specified TextElement is empty (has no printatble content).
bool IsElementEmpty(TextElement element)
    // Find starting and ending insertion positions in the element.
    // Inward-facing directions are used to make sure that insertion position
    // will be found correctly in case when the element may contain inline 
    // formatting elements (such as a Span or Run that contains Bold or Italic elements).
    TextPointer start = element.ContentStart.GetInsertionPosition(LogicalDirection.Forward);
    TextPointer end = element.ContentEnd.GetInsertionPosition(LogicalDirection.Backward);

    // The element has no printable content if its first and last insertion positions are equal.
    return start.CompareTo(end) == 0;

} // End IsEmptyElement method.

.NET Framework

Supported in: 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.