Positions and Ranges
- 7 minutes to read
Position and range are key entities in Word Processing Document API. 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 caret. 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:
using (var wordProcessor = new RichEditDocumentServer())
{
Document document = wordProcessor.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");
}
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:
document.Images.Insert(document.Range.End,
DocumentImageSource.FromFile("Documents//DevExpress.png"));
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 | ||
Paragraph | ||
Section | ||
Image | ||
Shape | ||
Table | ||
Hyperlink | ||
Bookmark | ||
Comment | ||
Field |
The code sample below retrieves all images from the document and moves the first image to the header:
Document document = wordProcessor.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);
}
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 following article for more information on how to format text: Text Formatting
using (RichEditDocumentServer server = new RichEditDocumentServer())
{
Document document = server.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);
server.SaveDocument("result.docx", DocumentFormat.OpenXml);
}
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:
using (RichEditDocumentServer server = new RichEditDocumentServer())
{
Document document = server.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);
server.SaveDocument("result.docx", DocumentFormat.OpenXml);
}
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.
using (RichEditDocumentServer server = new RichEditDocumentServer())
{
Document document = server.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");
server.SaveDocument("result.docx", DocumentFormat.OpenXml);
}
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.
using (RichEditDocumentServer server = new RichEditDocumentServer())
{
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);
server.SaveDocument("result.docx", DocumentFormat.OpenXml);
}