A Selection object describes which content has been selected in a document, and are generally obtained using the Document object’s selection property.
A Selection object can represent an insertion point (a zero-length text selection), a single contiguous selection, or a multi-part (discontinuous) selection. Selection objects come in a variety of flavors, but they are all related:
1. Selection object represents any selection: text or table, single or multi-part.
2. TextSelection object represents a single contiguous region of text characters.
3. TableSelection object represents a single contiguous region of table cells.
A selection can also mix text selections and table selections. The Selection object provides a unified interface to any kind of selection the user may have in a document.
Selection Type Commands
Selection.newCombining [selections], [selections] ... v2.0.5
Returns a Selection object that joins together all of the given Selection objects. These can be any kind of selection objects: Selection, TextSelection, or TableSelection. Any arguments to this command can also be an array of such selection objects.
Selection.newWithRecreationTokenInDocument token, document v2.1
Returns a Selection object that is reconstituted using the data in the provided token, which is a string previously created using the command recreationToken. The Document object given to this command must be the same document that held the original tokenized selection.
This command can return the @undefined value if the token is invalid or the selection cannot be reconstituted.
Selection Object Properties
.textSelection v2.0.5
Returns a TextSelection object for the first contiguous text selection. Read-only.
Returns an array of all TextSelection objects comprising the selection, one for each separate contiguous text selection. Read-only.
The selections in the returned array are sorted first by Text object and then by character location in ascending order.
The ranges for all selections in a particular text object are always disjoint (ie: a particular selected character can only belong to a single selection). Any adjacent/kissing selections the user has made are always represented using a single selection (eg: they are coalesced). There can be a zero length selection only if it is the only selection in the document (an insertion point).
Returns a TableSelection object for the first table selection in the selection, or the @undefined value if there are no table selections. Read-only.
A table selection exists if any part of a table cell’s text is selected, the insertion point rests in a table cell, or multiple table cells are selected.
Returns an array of all TableSelection objects in the selection, or the @undefined value if there are no table selections. Read-only.
The selections in the returned array are sorted first by Table object, then by row index, then by column index, in ascending order. The regions described for a particular table are always disjoint (eg: any single cell can only belong to a single selection, if any).
A Text object that joins together all the selected content. If the selection is zero-length (ie: an insertion point) then an empty string is returned. Read-only.
Note that the returned object is different than the Text object that would be obtained by using the text property of a Document or TextSelection object. The latter contain all logically connected content in a particular text area (eg: document body), while this property returns a text value that holds just the content that has been selected.
An array of Text objects, one for each disjoint element in a multi-part selection. Read-only.
As with the subtext property, these values are constructed to hold just the selected text.
A string that contains joins all the plain text of the selected content. Read-only.
This property is more efficient than subtext if attributes and special content are unimportant.
An array of strings, one for each disjoint element in a multi-part selection. Read-only.
This property is more efficient than subtexts if attributes and special content are unimportant.
How many distinct noncontiguous substrings (ie: text selections) are in the selection. Read-only.
This property is more efficient than using substring or substrings if the text itself is unimportant.
Returns the first Attributes object associated with the selection. This is either the formatting applied to the first selected character, or if there’s no selection (ie: an insertion point) returns the typing attributes (see below). Read-only.
.firstDisplayAttributes v3.0.2
This command works just like firstAttributes but returns display attributes. For more on display attributes see displayAttributesAtIndex.
Returns the Attributes object associated with the insertion point; that is, the formatting that would be applied to newly inserted text. These attributes may not yet have been applied to any text in the document.
These attributes are analogous to the Text object’s attributes in that any formatting property not explicitly set will have an @undefined value. Please see attributesAtIndex and displayAttributesAtIndex for more on the difference between attributes and display attributes.
.displayTypingAttributes v2.0.5
Just like typingAttributes but returns display attributes. For more on display attributes see displayAttributesAtIndex.
.styles v2.0.5
Returns an array of Style objects that are applied to the selection, in no particular order. If no styles are applied to the selected text, returns the @undefined value.
Returns the first character Style object that is applied to the selected. If no character style is applied to the selected text, returns the @undefined value.
Behaves just like characterStyle, but returns a paragraph style instead.
Behaves just like characterStyle, but returns a list style instead.
Behaves just like characterStyle, but returns a note style instead.
An array of Table objects, one for each table that is directly selected (ie: where the user has actually selected some or all of the cells in a table). Read-only.
An array of Table objects, one for each table that is either directly selected or enclosed in any constituent text selection. Read-only.
The first directly selected Image object, or @undefined if none. Read-only.
An array of Image objects, one for each image that is directly selected. Read-only.
An array of Image objects, one for each image that is either directly selected or enclosed in any constituent text selection. Read-only.
The first directly selected FloatingContent object, or @undefined if none. Read-only.
An array of FloatingContent objects, one for each floating content that is directly selected. Read-only.
.enclosedFloatingContents v2.0.5
An array of FloatingContent objects, one for each floating content that is either directly selected or where any constituent text selection intersects the floating content’s anchoring paragraph. Read-only.
Selection Object Commands
.combineSelection otherSelection v2.0.5
Returns a new Selection object that selects all content described in both selections.
Returns a string that can later be used to recreate this selection using the command Selection.newWithRecreationTokenInDocument.
If changes occur to the document (eg: user inserting text) after the token is obtained, it may no longer resolve back to a selection for the same logical content. The selection endpoints may shift.
This token is only valid as long as the document remains open. In other words, this token cannot be stored across application relaunch, and becomes invalid if the document is closed.
| Previous Chapter Selection Objects |
<< index >> |
Next Chapter TextSelection Object |