Edit this page

Positioning

The positioning feature in the RadRichTextBox is used to navigate through document's content and to get information about the document's elements at a specific position. The RadDocument uses the positioning to track the movement of the caret and to control the selection.

Overview

The positioning is implemented via the DocumentPosition class. This class can be used by the developer to programmatically control the positioning or the selection. DocumentPosition offers methods, such as MoveToNextWord(), MoveToPreviousWord(), MoveToCurrentLineStart/End() and so on, which will navigate to the given document element. In order to get information about the element at a given position you can use several methods such as GetCurrentSpanBox(), GetCurrentParagraphBox(), GetCurrentSectionBox() and so on.

DocumentPosition also redefines equality and comparison operators for more convenience, when you should find whether the DocumentPosition is before or after another position in the natural flow of the document. By default RadRichTextBox moves Document.CaretPosition using arrow keys or on mouse click. DocumentPosition can also be obtained by giving the coordinates of a point in the document using the method DocumentPosition.SetPosition.

You can manage the caret position for a specific RadDocument by either accessing its CaretPosition property, which is of type DocumentPosition, or by creating a new instance of the DocumentPosition class and associating it with the desired RadDocument.

When using the CaretPosition property you are directly managing the caret position in the RadDocument. By using the DocumentPosition class you can create instances of several positions inside the document without changing the current caret position.

CaretPosition property

Here is an example of how to use the CaretPosition property to get the current word.

Example 1: Getting the word on the caret position

string currentSpanText = this.radRichTextBox.Document.CaretPosition.GetCurrentSpanBox().Text;
Dim currentSpanText As String = Me.radRichTextBox.Document.CaretPosition.GetCurrentSpanBox().Text

DocumentPosition class

An alternative of using the CaretPosition property is to create an instance of the DocumentPosition class. Here is the same example from the previous chapter done with an instance of the DocumentPosition class.

When instantiated in such a way, the position will be at the start of the document, so the result will be the first word in the text.The position of the instance won't be affected by the UI. To change it you have to use the API of the DocumentPosition class.

Example 2: Getting the word on the caret using the DocumentPosition class

DocumentPosition position = new DocumentPosition( this.radRichTextBox.Document );
string currentSpanText = position.GetCurrentSpanBox().Text;
Dim position As New DocumentPosition(Me.radRichTextBox.Document)
Dim currentSpanText As String = position.GetCurrentSpanBox().Text

To set selection range in RadRichTextBox you can use the DocumentPosition class. You can read more about this in the Selection help article.

Access document element from caret position

You can use the methods of the DocumentPosition class to get the document element on the caret position. The following list shows the methods which can be used.

  • GetCurrentInlineBox
  • GetCurrentSpanBox
  • GetCurrentParagraphBox
  • GetCurrentSectionBox
  • GetCurrentTableBox
  • GetCurrentTableRowBox
  • GetCurrentTableCellBox

The GetCurrent[document element]Box methods return objects of type LayoutBox which can be used to get the relevant document element. To get the element you can use the AssociatedDocumentElement property.

In the different implementations of the LayoutBox class (examples: ParagraphLayoutBox, SectionLayoutBox, etc.) there are also more specific properties that allow you to easily get the associated document element without casting it from the base DocumentElement class. For example, the GetCurrentParagraphBox() method returns an object of type ParagraphLayoutBox which has AssociatedParagraph property. And the GetCurrentSectionBox() returns SectionLayoutBox which has AssociatedSection property. This rule applies to all LayoutBox elements (also TableLayoutBox, SpanLayoutBox, etc.).

Example 3: Getting the Paragraph on the caret position

DocumentPosition documentPosition = radRichTextBox.Document.CaretPosition;
ParagraphLayoutBox paragraphBox = documentPosition.GetCurrentParagraphBox();
Paragraph paragraph = paragraphBox.AssociatedParagraph;             
Dim documentPosition As DocumentPosition = radRichTextBox.Document.CaretPosition
Dim paragraphBox As ParagraphLayoutBox = documentPosition.GetCurrentParagraphBox()
Dim paragraph As Paragraph = paragraphBox.AssociatedParagraph

There is also a GetCurrentInline method that returns directly the inline element on the caret position.

Example 4: Getting the Inline on the caret position

DocumentPosition documentPosition = radRichTextBox.Document.CaretPosition;
Inline inline = documentPosition.GetCurrentInline();
Dim documentPosition As DocumentPosition = radRichTextBox.Document.CaretPosition
Dim inline As Inline = documentPosition.GetCurrentInline()

To get the word on the document position you can use the GetCurrentWord method.

Example 5: Getting the word on the caret position

DocumentPosition documentPosition = radRichTextBox.Document.CaretPosition;
string word = documentPosition.GetCurrentWord();    
Dim documentPosition As DocumentPosition = radRichTextBox.Document.CaretPosition
Dim word As String = documentPosition.GetCurrentWord()

If the searched document element (paragraph, span, table, etc.) cannot be found on the caret position, the corresponding method will return null.

Convert between DocumentPosition and screen position

You can use the ActiveDocumentPresenter of RadRichTextBox to convert a screen position to DocumentPosition and vice versa. The ActiveDocumentPresenter expose couple methods which can be used.

  • GetDocumentPositionFromViewPoint: The method accepts an argument of type System.Windows.Point and returns an instance of type DocumentPosition.

    Example 6: Screen position to DocumentPosition conversion

        Point position = GetMousePosition();
        DocumentPosition documentPosition = radRichTextBox.ActiveEditorPresenter.GetDocumentPositionFromViewPoint(position);
    
        Dim position As Point = GetMousePosition()
        Dim documentPosition As DocumentPosition = radRichTextBox.ActiveEditorPresenter.GetDocumentPositionFromViewPoint(position)
    
  • GetViewPointFromDocumentPosition: The method accepts an argument of type DocumentPosition and returns an instance of type System.Windows.Point

    Example 7: DocumentPosition to screen position conversion

        DocumentPosition documentPosition = radRichTextBox.Document.CaretPosition;
        Point position = radRichTextBox.ActiveEditorPresenter.GetViewPointFromDocumentPosition(documentPosition);
    
        Dim documentPosition As DocumentPosition = radRichTextBox.Document.CaretPosition
        Dim position As Point = radRichTextBox.ActiveEditorPresenter.GetViewPointFromDocumentPosition(documentPosition)
    

See Also