# Positioning

The positioning feature in the **RadRichTextEditor** 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.

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 which will return the LayoutBox of an element. Another option is to use directly the methods returning the specific document element - **GetCurrentSpan()**, **GetCurrentParagraph()**, **GetCurrentTable()** etc.

**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, **RadRichTextEditor** 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**.

> note 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

This property enables you to manage the position of the caret inside the document and to obtain information about its location and the elements it currently resides at. Here is an example of how to use the **CaretPosition** property to get the current word.

```C#
string currentSpanText = this.radRichTextEditor1.Document.CaretPosition.GetCurrentSpanBox().Text;

```

```VB.NET
Dim currentSpanText As String = Me.radRichTextEditor1.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.

> note 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](https://docs.telerik.com/devtools/winforms/api/telerik.winforms.documents.documentposition).

```C#
Telerik.WinForms.Documents.DocumentPosition position = new Telerik.WinForms.Documents.DocumentPosition(this.radRichTextEditor1.Document);
string currentSpanText1 = position.GetCurrentSpanBox().Text;

```

```VB.NET
Dim position As New Telerik.WinForms.Documents.DocumentPosition(Me.radRichTextEditor1.Document)
Dim currentSpanText1 As String = position.GetCurrentSpanBox().Text

```

### Tracking Positions

When you need to ensure that the position is kept between the same characters, no matter the modifications users can do on the document content, you can instantiate the **DocumentPosition** object using one of the constructors accepting a boolean value. This boolean value indicates whether the position should track the changes in the document and move accordingly so it can be located on the same position in the word.

**DocumentPosition** created with any of the constructors accepting the boolean *trackDocumentChangeEvents* parameter set to *true* moves automatically when the document is edited before the position (just like the caret position).

> note Positions created in such a way could be explicitly disposed to avoid preserving them too much in memory.

## Determine The Type of Element The Position Is At

The **DocumentPosition** class offers different properties allowing you to determine where the position is located. For example, you can check whether the position is at the start of the document or at its end. Similarly, you can obtain information whether the position is inside table. Here is a list of these properties:

* **IsPositionAtDocumentEnd**
* **IsPositionAtDocumentStart**
* **IsPositionAtParagraphEnd**
* **IsPositionAtParagraphStart**
* **IsPositionAtTableCellEnd**
* **IsPositionAtTableCellStart**
* **IsPositionAtTableRowStart**
* **IsPositionInsideTable**

There is also a **Location** property holding information about where in the layout the position is situated.

## Access Document Element from Caret Position

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

* **GetCurrentInline()**
* **GetCurrentParagraph()**
* **GetCurrentSpan()**
* **GetCurrentTable()**
* **GetCurrentTableCell()**
* **GetCurrentTableRow()**
* **GetNextInline()**
* **GetNextSpan()**
* **GetPreviousInline()**

In addition to the above-mentioned methods, **DocumentPosition** exposes also **GetCurrent\[document element]Box** methods returning objects of type **LayoutBox**, which can be used to get the relevant layout information about a document element. To get the element from the layout box, 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.).

#### Getting the Paragraph on the caret position

```C#
DocumentPosition documentPosition = this.radRichTextEditor1.Document.CaretPosition;
Paragraph paragraph = documentPosition.GetCurrentParagraph();
```

```VB.NET
Dim documentPosition As DocumentPosition = Me.radRichTextEditor1.Document.CaretPosition()
Dim paragraph As Paragraph = documentPosition.GetCurrentParagraph()

```

#### Getting the Inline on the caret position

```C#
documentPosition = this.radRichTextEditor1.Document.CaretPosition;
Inline inline = documentPosition.GetCurrentInline();
```

```VB.NET
documentPosition = Me.radRichTextEditor1.Document.CaretPosition
Dim inline As Inline = documentPosition.GetCurrentInline()

```

To get the word on the document position, you can use the **GetCurrentWord()** method.

#### Getting the word on the caret position

```C#
documentPosition = this.radRichTextEditor1.Document.CaretPosition;
string word = documentPosition.GetCurrentWord();
```

```VB.NET
documentPosition = Me.radRichTextEditor1.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 **ActiveEditorPresenter** of **RadRichTextEditor** to convert a screen position to **DocumentPosition** and vice versa. The **ActiveEditorPresenter** exposes a couple of methods which can be used.

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

#### Screen position to DocumentPosition conversion

```C#
Point position = GetMousePosition();
DocumentPosition documentPosition = this.radRichTextEditor1.RichTextBoxElement.ActiveEditorPresenter.GetDocumentPositionFromViewPoint(position);
```

```VB.NET
Dim position As System.Drawing.Point = GetMousePosition()
Dim documentPosition As DocumentPosition = Me.radRichTextEditor1.RichTextBoxElement.ActiveEditorPresenter.GetDocumentPositionFromViewPoint(position)

```

* **GetViewPointFromDocumentPosition()**: The method accepts an argument of type DocumentPosition and returns an instance of type System.Windows.Point

#### DocumentPosition to screen position conversion

```C#
documentPosition = this.radRichTextEditor1.Document.CaretPosition;
position = this.radRichTextEditor1.RichTextBoxElement.ActiveEditorPresenter.GetViewPointFromDocumentPosition(documentPosition);
```

```VB.NET
documentPosition = Me.radRichTextEditor1.Document.CaretPosition
position = Me.radRichTextEditor1.RichTextBoxElement.ActiveEditorPresenter.GetViewPointFromDocumentPosition(documentPosition)
```

## Events

There are several events that you can use to track changes in the position.

* **LocationChanging**: Occurs before changing the coordinates of a position. For the caret position, this can be also achieved by typing, using the arrows keys or by clicking somewhere in the document.

LocationChanged: Occurs when changing the coordinates of a position. For the caret position, this can be also achieved by typing, using the arrows keys or by clicking somewhere in the document.

* **PositionChanging**: Occurs before the position is moved. For the caret position, this can be also achieved using the arrows keys or by clicking somewhere in the document.

* **PositionChanged**: Occurs when the position is moved. For the caret position, this can be also achieved using the arrows keys or by clicking somewhere in the document.

The following example shows how you can change the background of a Table object once the caret is positioned inside a Table.

#### Using DocumentPosition events

```C#
private void CaretPosition_LocationChanged(object sender, EventArgs e)
{
    if (this.radRichTextEditor1.Document.CaretPosition.IsPositionInsideTable)
    {
        Table table = this.radRichTextEditor1.Document.CaretPosition.GetCurrentTable();
        table.Background = Colors.Red;
    }
}
```

```VB.NET
Private Sub CaretPosition_LocationChanged(ByVal sender As Object, ByVal e As EventArgs)
    If Me.radRichTextEditor1.Document.CaretPosition.IsPositionInsideTable Then
        Dim table As Table = Me.radRichTextEditor1.Document.CaretPosition.GetCurrentTable()
        table.Background = Colors.Red
    End If
End Sub
```

## See Also

* [Section](https://www.telerik.com/products/winforms/documentation/controls/richtexteditor/document-elements/section)

* [History](https://www.telerik.com/products/winforms/documentation/controls/richtexteditor/features/history)