Positions and Ranges

Apr 23, 2025
7 minutes to read

Position and range are key entities in the RichEditControl. They define the location of every object in a document model.

Position

Position (the DocumentPosition object) is a zero-based index of every symbol in a document. Each position identifies a possible placement for a text cursor. Position 0 is the beginning of a document and precedes the first character. When the caret moves to the next character, it moves to position 1 and so on.

Obtain a Position

The following code sample calls the SubDocument.CreatePosition method to obtain the document position at the given index and inserts a text in it:

C#
VB.NET

csharp

Document document = richEditControl.Document;
DocumentPosition pos1 = document.CreatePosition(2);
document.InsertText(pos1,"The Word Processing Document API is a non-visual .NET library.\r
It allows you to automate frequent word processing tasks.\n");

Dim document As Document = richEditControl.Document
Dim pos1 As DocumentPosition = document.CreatePosition(2)
document.InsertText(pos1, "The Word Processing Document API is a non-visual .NET library. It allows you to automate frequent word processing tasks")

You can use DocumentPosition objects to insert other elements into a document. The table below lists APIs that use a position as a parameter or returns a DocumentPosition object.

API	Description
SubDocument.InsertText	Inserts a given text string at the specified position.
SubDocument.InsertDocumentContent	Inserts content from a range, stream or text string at the specified position.
ParagraphCollection.Insert	Insert a new paragraph at the specified position.
Document.InsertSection	Inserts a section break at the given position.
FieldCollection.Create	Creates a new field at the specified position.
BookmarkCollection.Create	Creates a new bookmark at the given position.
FormFieldCollection.InsertCheckBox	Creates a new checkbox at the given position.
ShapeCollection.InsertPicture	Inserts a new image at the given position.
ShapeCollection.InsertTextBox	Inserts a new text box at the given position.
CommentCollection.Create	Creates a comment anchored to the specified position
TableCollection.Create	Inserts a new table with the given number of rows and columns in the specified position.

The code sample below appends an image at the end of the document:

C#
VB.NET

csharp

document.Images.Insert(document.Range.End,
DocumentImageSource.FromFile("Documents//DevExpress.png"));

document.Images.Insert(document.Range.End,
DocumentImageSource.FromFile("Documents//DevExpress.png"))

Obtain the Position’s Location

Use the following methods to obtain an approximate location of the required position.

RichEditControl.GetBoundsFromPosition - obtains coordinates of the rectangle surrounding the specified document position.
RichEditControl.GetPositionFromPoint - locates the position close to the specified point.
RichEditView.GetCursorBounds - retrieves coordinates of a rectangle encompassing the cursor.

Note

If you operate with a selection range, any of the above-listed methods should be enclosed within DocumentRange.BeginUpdateDocument - DocumentRange.EndUpdateDocument methods pair. Otherwise, an incorrect document model might be selected, resulting in an exception “Error: specified document position or range belongs to other document or subdocument” being thrown.

Range

The range (the DocumentRange object) is an interval between two positions (DocumentRange.Start and DocumentRange.End). The difference between them is equal to DocumentRange.Length.

Obtain a Range

Use the SubDocument.CreateRange method to create a new DocumentRange object with the specified start and end positions.

The following API allows you to obtain a range associated with document elements or obtain elements from a specified range:

Object

Obtain a Range Related to an Element

Retrieve an Element from a Range

| | --- | --- | --- | |

Text

SubDocument.Range

SubDocument.GetText

SubDocument.GetRtfText

SubDocument.GetHtmlText

SubDocument.GetMhtText

SubDocument.GetDocxBytes

SubDocument.GetDocBytes

| |

Paragraph

Paragraph.Range

ReadOnlyParagraphCollection.Get

| |

Section

Section.Range

Document.GetSection

| |

Image

Image.Range

ReadOnlyDocumentImageCollection.Get

| |

Shape

Shape.Range

ReadOnlyShapeCollection.Get

| |

Table

Table.Range

ReadOnlyTableCollection.Get

| |

Hyperlink

Hyperlink.Range

ReadOnlyHyperlinkCollection.Get

| |

Bookmark

Bookmark.Range

ReadOnlyBookmarkCollection.Get

| |

Comment

Comment.Range

ReadOnlyCommentCollection.Get

| |

Field

Field.Range

ReadOnlyFieldCollection.Get

The code sample below retrieves all images from the document and moves the first image to the header:

C#
VB.NET

csharp

Document document = richEditControl.Document;
if (document.Images.Count != 0)
{
    //Obtain all images
    ReadOnlyDocumentImageCollection images = document.Images.Get(document.Range);

    //Start the header update
    SubDocument header = document.Sections[0].BeginUpdateHeader();

    //Insert the retrieved image in the header
    header.Images.Insert(header.Range.Start, images[0].Image.NativeImage);
    header.EndUpdate();

    //Remove the image from its initial place
    document.Delete(images[0].Range);
}

Dim document As Document = richEditControl.Document

If document.Images.Count <> 0 Then
   'Obtain all images
   Dim images As ReadOnlyDocumentImageCollection = document.Images.Get(document.Range)

   'Start the header's update
   Dim header As SubDocument = document.Sections(0).BeginUpdateHeader()

   'Insert the retrieved image in the header
   header.Images.Insert(header.Range.Start, images(0).Image.NativeImage)
   header.EndUpdate()

   'Remove the image from its initial place
   document.Delete(images(0).Range)
End If

How Content Modifications Affect Ranges

When you modify content within a range, the range can expand or shrink automatically.

If you append a single line to a document and change its format options, the format is applied to the new content only.

Tip

Refer to the Text Formatting article for more information on how to format text.

C#
VB.NET

csharp

Document document = richEditControl.Document;

//Append the line
DocumentRange newRange = document.AppendText("Word Processing Document API\r\n");

//Change the range's format options
CharacterProperties characterProperties = document.BeginUpdateCharacters(newRange);
characterProperties.ForeColor = Color.DarkGray;
characterProperties.FontSize = 16;
characterProperties.FontName = "Georgia";
characterProperties.Italic = true;
document.EndUpdateCharacters(characterProperties);

richEditControl.SaveDocument("result.docx", DocumentFormat.Docx);

Dim document As Document = richEditControl.Document

'Append the line
Dim newRange As DocumentRange = document.AppendText("Word Processing Document API" & ControlChars.CrLf)

'Change the range's format options
Dim characterProperties As CharacterProperties = document.BeginUpdateCharacters(newRange)
characterProperties.ForeColor = Color.DarkGray
characterProperties.FontSize = 16
characterProperties.FontName = "Georgia"
characterProperties.Italic = True
document.EndUpdateCharacters(characterProperties)

server.SaveDocument("result.docx", DocumentFormat.Docx)

If you sequentially append multiple fragments to a document, the DocumentRange object may expand with each new added fragment. The examples below demonstrate the possible results and two ways to resolve these issues.

Append two lines of text and then change the range’s formatting, as shown below:

C#
VB.NET

csharp

Document document = richEditControl.Document;

//Append the first line
DocumentRange newRange = document.AppendText("Word Processing Document API\r\n");

//Append the second line
document.AppendText("The Word Processing Document API is a non-visual .NET library.\r " +
    "It allows you to automate frequent word processing tasks.\n");

//Change the range's format options
CharacterProperties characterProperties = document.BeginUpdateCharacters(newRange);
characterProperties.ForeColor = Color.DarkGray;
characterProperties.FontSize = 16;
characterProperties.FontName = "Georgia";
characterProperties.Italic = true;
document.EndUpdateCharacters(characterProperties);

richEditControl.SaveDocument("result.docx", DocumentFormat.Docx);

Dim document As Document = richEditControl.Document

'Append the first line
Dim newRange As DocumentRange = document.AppendText("Word Processing Document API" & ControlChars.CrLf)

'Append the second line
document.AppendText("The Word Processing Document API is a non-visual .NET library." & ControlChars.Cr & " " & "It allows you to automate frequent word processing tasks." & ControlChars.Lf)

'Change the range's format options
Dim characterProperties As CharacterProperties = document.BeginUpdateCharacters(newRange)
characterProperties.ForeColor = Color.DarkGray
characterProperties.FontSize = 16
characterProperties.FontName = "Georgia"
characterProperties.Italic = True
document.EndUpdateCharacters(characterProperties)

richEditControl.SaveDocument("result.docx", DocumentFormat.Docx)

When you execute this code, it changes the format of all the text.

Solution #1

Change the format options before inserting new content to avoid this behavior. In this case, the new content remains unformatted.

C#
VB.NET

csharp

Document document = richEditControl.Document;

//Append the first line
DocumentRange newRange = document.AppendText("Word Processing Document API\r\n");

//Apply formatting for the first line
CharacterProperties characterProperties = document.BeginUpdateCharacters(newRange);
characterProperties.ForeColor = Color.DarkGray;
characterProperties.FontSize = 16;
characterProperties.FontName = "Georgia";
characterProperties.Italic = true;
document.EndUpdateCharacters(characterProperties);

//Append the second line
document.AppendText("The Word Processing Document API is a non-visual .NET library.\r " +
"It allows you to automate frequent word processing tasks.\n");

richEditControl.SaveDocument("result.docx", DocumentFormat.Docx);

Dim document As Document = richEditControl.Document

'Append the first line
Dim newRange As DocumentRange = document.AppendText("Word Processing Document API" & ControlChars.CrLf)

'Apply formatting for the first line
Dim characterProperties As CharacterProperties = document.BeginUpdateCharacters(newRange)
characterProperties.ForeColor = Color.DarkGray
characterProperties.FontSize = 16
characterProperties.FontName = "Georgia"
characterProperties.Italic = True
document.EndUpdateCharacters(characterProperties)

'Append the second line
document.AppendText("The Word Processing Document API is a non-visual .NET library." & ControlChars.Cr & " " & "It allows you to automate frequent word processing tasks." & ControlChars.Lf)

richEditControl.SaveDocument("result.docx", DocumentFormat.Docx)

Solution #2

Another way to format the initial content is to store the target range’s position and length and create a new DocumentRange object.

The code sample below appends two lines to the document, but changes the format options only for the first line.

C#
VB.NET

csharp

Document document = server.Document;

//Append the first line
DocumentRange newRange = document.AppendText("Word Processing Document API.\r\n");

//Preserve the range's start position and length
int rangeStart = newRange.Start.ToInt();
int rangeLength = newRange.Length;

//Append the second line
document.AppendText("The Word Processing Document API is a non-visual .NET library.\r " +
    "It allows you to automate frequent word processing tasks.\n");

//Recreate the initial range
DocumentRange formattedRange = document.CreateRange(rangeStart, rangeLength);

//Format the target range
CharacterProperties characterProperties = document.BeginUpdateCharacters(formattedRange);
characterProperties.ForeColor = Color.DarkGray;
characterProperties.FontSize = 16;
characterProperties.FontName = "Georgia";
characterProperties.Italic = true;
document.EndUpdateCharacters(characterProperties);

richEditControl.SaveDocument("result.docx", DocumentFormat.Docx);

Dim document As Document = richEditControl.Document

'Append the first line
Dim newRange As DocumentRange = document.AppendText("Word Processing Document API." & ControlChars.CrLf)

'Preserve the range's start and length
Dim rangeStart As Integer = newRange.Start.ToInt()
Dim rangeLength As Integer = newRange.Length

'Append the second line
document.AppendText("The Word Processing Document API is a non-visual .NET library." & ControlChars.Cr & " " & "It allows you to automate frequent word processing tasks." & ControlChars.Lf)

'Recreate the initial range
Dim formattedRange As DocumentRange = document.CreateRange(rangeStart, rangeLength)

'Format the target range
Dim characterProperties As CharacterProperties = document.BeginUpdateCharacters(formattedRange)
characterProperties.ForeColor = Color.DarkGray
characterProperties.FontSize = 16
characterProperties.FontName = "Georgia"
characterProperties.Italic = True
document.EndUpdateCharacters(characterProperties)

richEditControl.SaveDocument("result.docx", DocumentFormat.Docx)