Client Selection
- 6 minutes to read
The RichEdit provides a comprehensive API, allowing you to access and modify the current selection in a document on the client side. To access the selection-related client API, use the RichEdit’s ASPxClientRichEdit.selection property, which returns a RichEditSelection object. With properties and methods of this object, you can perform your tasks on the selection.
Selection can be defined using the following three characteristics: an active sub-document, a list of selected intervals in the sub-document and the active page’s index (in case the active sub-document’s type is not SubDocumentType.Main).
To change the active sub-document, you can use the following commands. (Note that commands related to headers/footers or text boxes can create a sub-document or the specified type if it does not exist.)
setActiveSubDocumentById (RichEditSelection.setActiveSubDocumentById)
richEdit.selection.setActiveSubDocumentById([sub-document_id])setMainSubDocumentAsActive (RichEditSelection.setMainSubDocumentAsActive)
richEdit.selection.setMainSubDocumentAsActive()setFooterSubDocumentAsActiveByPageIndex (RichEditSelection.setFooterSubDocumentAsActiveByPageIndex)
richEdit.selection.setFooterSubDocumentAsActiveByPageIndex([page_index])setHeaderSubDocumentAsActiveByPageIndex (RichEditSelection.setHeaderSubDocumentAsActiveByPageIndex)
richEdit.selection.setHeaderSubDocumentAsActiveByPageIndex([page_index])setTextBoxSubDocumentAsActive (RichEditSelection.setTextBoxSubDocumentAsActive)
richEdit.selection.setTextBoxSubDocumentAsActive([anchor_position])
You can apply the selection at runtime or on the client using the RichEditSelection.setSelection method. Examples of applying different interval selections are illustrated below.
Collapsed selection (the cursor position)
The selected interval count is 1, and the length of this interval is 0.
Code
Result
richEdit.selection.setSelection(9);
richEdit.selection.intervals === [{ start: 9, length: 0 }]
Expanded selection
There is a single selected interval of non-zero length.
Code
Result
richEdit.selection.setSelection(new ASPx.Interval(10, 3));
richEdit.selection.intervals === [{ start: 10, length: 3 }]
Multiple selection
There are multiple selected intervals of non-zero lengths.
Code
Result
richEdit.selection.setSelection([new ASPx.Interval(5, 1), new ASPx.Interval(9, 1)]);
richEdit.selection.intervals === [{ start: 5, length: 1 }, { start: 9, length: 1 }]
Example (Creating a Header)
// Stores current selected intervals of the main sub-document
var intervals = rich.selection.intervals;
// Creates a header sub-document (if it was not created before) and sets the header as the active sub-document. Defines selection.intervals as { start: 0, length: 0}
richEdit.selection.setHeaderSubDocumentAsActiveByPageIndex(0);
// Inserts text into the header to the current position of selected intervals
richEdit.commands.insertText.execute("Header text");
// Changes the active sub-document back to the main sub-document
richEdit.selection.setMainSubDocumentAsActive();
// Applies the previously saved selection
richEdit.selection.intervals = intervals;
Most client commands are based on the selection. For instance, in the previous code example, the insertText client command inserts the specified text into the position indicated by the selection’s intervals property (which is by default set to {start: 0, length: 0} for a created header sub-document).
API Listing
The main client properties affecting the selection are listed below. Access them in the following notation.
clientRichEditName.selection.propertyName
| Property Name | Link | Description |
|---|---|---|
| Get or set the selection state | ||
| intervals | RichEditSelection.intervals | Gets or sets an array of document intervals in the selection. |
| collapsed | RichEditSelection.collapsed | Gets or sets a value specifying whether the current selection is collapsed (and represents the cursor position). |
| Receive information about the current selection | ||
| getIntervalMaxPosition | RichEditSelection.getIntervalMaxPosition | Gets the maximum position of a document interval in the selection. |
| isTextBoxSelected | RichEditSelection.isTextBoxSelected | Gets whether only a text box is selected. |
| isPictureSelected | RichEditSelection.isPictureSelected | Gets whether only a picture is selected. |
| isFloatingObjectSelected | RichEditSelection.isFloatingObjectSelected | Gets whether a floating picture or text box is selected. |
The following client methods are available for manipulating the selection in a document. Call the methods in the notation given below.
clientRichEditName.selection.methodName([parameter_if_any])
| Method Name | Link | Description |
|---|---|---|
| Change the active sub-document | ||
| setMainSubDocumentAsActive | RichEditSelection.setMainSubDocumentAsActive | Makes the main sub-document active and moves the cursor to its beginning. |
| setFooterSubDocumentAsActiveByPageIndex | RichEditSelection.setFooterSubDocumentAsActiveByPageIndex | Creates a footer sub-document (if it was not created before) and sets the footer as the active sub-document. Moves the cursor to the footer’s start position. |
| setHeaderSubDocumentAsActiveByPageIndex | RichEditSelection.setHeaderSubDocumentAsActiveByPageIndex | Creates a header sub-document (if it was not created before) and sets the header as the active sub-document. Moves the cursor to the header’s start position. |
| Change selection by specifying intervals | ||
| setSelection | RichEditSelection.setSelection | Defines the selection to the specified interval. |
| Change selection by manipulating the document model | ||
| selectAll | RichEditSelection.selectAll | Selects the editor’s entire content. |
| goToDocumentStart | RichEditSelection.goToDocumentStart | Moves the cursor to the start of the document and allows you to extend the selection. |
| goToDocumentEnd | RichEditSelection.goToDocumentEnd | Moves the cursor to the end of the document and allows you to extend the selection. |
| goToParagraphStart | RichEditSelection.goToParagraphStart | Moves the cursor to the start of the paragraph in which the cursor is located and allows you to extend the selection. |
| goToParagraphEnd | RichEditSelection.goToParagraphEnd | Moves the cursor to the end of the paragraph in which the cursor is located and allows you to extend the selection. |
| selectParagraph | RichEditSelection.selectParagraph | Selects the paragraph in which the cursor is located. |
| Change selection by manipulating the document layout | ||
| goToNextLine | RichEditSelection.goToNextLine | Moves the cursor to the next line and allows you to extend the selection. |
| goToPreviousLine | RichEditSelection.goToPreviousLine | Moves the cursor to the previous line and allows you to extend the selection. |
| goToLineEnd | RichEditSelection.goToLineEnd | Moves the cursor to the end of the line in which the cursor is located and allows you to extend the selection. |
| goToLineStart | RichEditSelection.goToLineStart | Moves the cursor to the start of the line in which the cursor is located and allows you to extend the selection. |
| goToNextCharacter | RichEditSelection.goToNextCharacter | Moves the cursor to the next character and allows you to extend the selection. |
| goToPreviousCharacter | RichEditSelection.goToPreviousCharacter | Moves the cursor to the previous character and allows you to extend the selection. |
| selectLine | RichEditSelection.selectLine | Selects the line in which the cursor is located and allows you to extend the entire selection with the currently existing selection. |
| goToNextPage | RichEditSelection.goToNextPage | Moves the cursor to the beginning of the next page and allows you to extend the selection. |
| goToPreviousPage | RichEditSelection.goToPreviousPage | Moves the cursor to the beginning of the previous page and allows you to extend the selection. |
| goToNextWord | RichEditSelection.goToNextWord | Moves the cursor to the next word and allows you to extend the selection. |
| goToStartNextPageCommand | RichEditSelection.goToStartNextPageCommand | Moves the cursor to the next page break mark and extends the selection. |
| goToStartPrevPageCommand | RichEditSelection.goToStartPrevPageCommand | Moves the cursor to the previous page break mark and extends the selection. |
| Change selection by manipulating tables | ||
| selectTableCell | RichEditSelection.selectTableCell | Selects the table cell in which the cursor is located and allows you to extend the entire selection with the currently existing selection. |
| selectTableRow | RichEditSelection.selectTableRow | Selects the table row in which the cursor is located and allows you to extend the entire selection with the currently existing selection. |
| selectTable | RichEditSelection.selectTable | Selects the entire table in which the cursor is located and allows you to extend the entire selection with the currently existing selection. |
Example (Working with Bookmark Selection)
In certain document elements (for instance, bookmarks) that do not have a dedicated selection API, you need to handle selection manually. The example below demonstrates how to work with selections in bookmarks.
var makeInterval = function (start, length) {
return { start: start, length: length };
}
var makeBookmarkInterval = function (bookmark) {
return makeInterval(bookmark.start, bookmark.length);
}
rich.commands.insertText.execute("bookmark1, bookmark2, bookmark3");
for (var bkmIndex = 0; bkmIndex < 3; bkmIndex++)
rich.commands.insertBookmark.execute("bookmark" + (bkmIndex + 1).toString(), bkmIndex * 11, 9);
var bkmInfos = rich.document.activeSubDocument.bookmarksInfo;
for (var bkmIndex = 0, bookmark; bookmark = bkmInfos[bkmIndex]; bkmIndex++)
if (bookmark.name === "bookmark1") {
rich.selection.intervals = [makeBookmarkInterval(bookmark)];
break;
}