A newer version of this page is available. Switch to the current version.

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.)

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 }]

    selection-collapsed.png

  • 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 }]

    selection-expanded.png

  • 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 }]

    selection-multiple.png

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;
    }