Positions and Ranges
- 3 minutes to read
The logical structure of a document exposed via XtraRichEdit API is based on the concepts of range and position. The position concept relates to the caret (text cursor) located in the text string. The document range is represented by several consecutive characters regardless of their format. Positions in the document are numbered starting from 0 (zero).
To get the current position in a document, use the Document.CaretPosition property. The SubDocument.CreatePosition method can be used to create a position in the document for passing it as the parameter to Document methods.
To create a DocumentRange, use the SubDocument.CreateRange method or select a block of text and take advantage of the Document.Selection property, which returns a selected range. Note that a range assignment to this property results in selecting a portion of the text.
Each structural unit of a document has a Range property representing a document range occupied by the unit. The length of the range is calculated as the difference between the final position and the starting position. The picture above shows that the length of the range is calculated by subtracting the starting position (DocumentRange.Start) from the final position (DocumentRange.End) , and equaling to 3.
A caret is defined by only one position and has a zero-length range. An inline image, represented by the DocumentImage object substitutes one character and is defined by two positions having a range length equal to 1. In contrast to these objects, a Field range consists of two parts - one for the Field.CodeRange and another for the Field.ResultRange.
To modify formatting of characters in a range, use the SubDocument.BeginUpdateCharacters - SubDocument.EndUpdateCharactersmethod pair.
To insert text in a document, use the SubDocument.InsertText or SubDocument.InsertSingleLineText methods. The last method performs better because less overhead is needed for line break calculations. You can insert formatted text by using the SubDocument.InsertRtfText method.
To delete text in the document, use the SubDocument.Delete method.
XtraRichEdit API implements several methods intended to retrieve text represented by the specified range in different formats. They are: SubDocument.GetText, SubDocument.GetRtfText, SubDocument.GetHtmlText, SubDocument.GetMhtText, SubDocument.GetOpenXmlBytes.
To obtain images contained in the specified range, use the SubDocument.GetImages method.
NOTE
For the specified Document
Since the logical and physical structures of the document are conceptually independent, there is no one to one correspondence between physical and logical entities. Thus, you cannot tell on what line and on what page a certain range or position is located. The RichEditControl.GetBoundsFromPosition method can help you to obtain the coordinates of the rectangle encompassing the visual representation of the specified document position. The RichEditControl.GetPositionFromPoint method enables you to locate the position that is situated close to the specified point.