TextSelection Object

A TextSelection object describes content that has been selected in a Text object, eg: a document body. The location and length describe which character indexes are included in the selection. The location is zero-based, eg: the first character in the text has an index of zero.

All indexes described by a selection are always in-bounds for the text object, unless the selection is zero length. If so the location may be set to the length of the text object (eg: caret at end of document).

Note: as of v2.0.5 you may treat any TextSelection object as a Selection object, eg: all properties/commands listed under Selection are valid for TextSelection objects.

TextSelection Type Commands

TextSelection.new text, [charRangeObject] v1.1

Returns a new selection that selects characters in the Range object within the given text object. The range must be in-bound for the text object or an error will be displayed. If the range is omitted, then the entire text object is selected.

If you intend to use the new TextSelection object to change the selection in a document, you must use a text object that originated from the document itself. It should also be the full text object (eg: main body, header, table cell, etc), not a portion of it. An example:

$doc = Document.active

$range = Range.new(0, $doc.text.length)

$selection = TextSelection.new($doc.text, $range)

$doc.setSelection($selection)

That example will select all the characters in the document. The following will fail because the text object is unrelated to the document:

$doc = Document.active

$range = Range.new(0, 2)

$selection = TextSelection.new("hello", $range)

$doc.setSelection($selection)

TextSelection.newWithLocationAndLength text, loc, len v1.1

Returns a new selection that selects the described characters within the given text object. The location and length must be in-bound for the text object or an error will be displayed.

TextSelection.newWithLocationAndBound text, loc, bound v1.1

Returns a new selection that selects the described characters within the given text object. The bound must not be less than the location or an error will be displayed.

TextSelection.active v1.1

Returns the first TextSelection object in the active Document, or the @undefined value if no document is active.

TextSelection.activeText v1.1

Returns the first selected Text object in the active Document, or the @undefined value if no document is active. Note: the returned text object follows reference semantics, eg: changes to it will change the contents of the document itself.

TextSelection.activeRange v1.1

Returns a Range object describing the first selection in the active Document, or the @undefined value if no document is active.

TextSelection.setActiveRange rangeObject v1.1

Changes the selection in the active Document so the characters described by the given Range object are selected in the active Text object.

TextSelection.activeSubtext v2.1

Returns a Text object that joins together all the selected content in the active Document. If the selection is zero-length (ie: an insertion point) then an empty string is returned.

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.

TextSelection.activeSubstring v2.1

Returns a string that joins together all the selected content in the active Document as plain text.

This property is more efficient than activeSubtext if attributes and special content are unimportant.

TextSelection Object Properties

.text v1.1

The Text object in which the selection has been made. This text object contains all the logically connected content (eg: the full document body, header, table cell, etc), not just the selected portion.

Note: the returned text object follows reference semantics, eg: changes to it will change the contents of the document itself.

.range v1.1

A Range object that describes which characters in the text object are selected. The range is zero-based (eg: the first character in the text object has location zero). Changing the range also changes the location, length, and bound properties.

.location v1.1

The index of the first selected character in the text object (zero-based). Note: if the selection is zero length, this is the index of the character that occurs after the caret. Changing the location also changes the bound and range properties.

.length v1.1

The number of selected characters. Changing the length also changes the bound and range properties.

.bound v1.1

The index of the first character after and outside the selection. If an attempt is made to set this property to a number less than the current location an error will be displayed. Changing the bound also changes the length and range properties.

.subtext v1.1

See Selection object’s subtext property.

.subtexts v2.0.5

See Selection object’s subtexts property.

.substring v1.3

See Selection object’s substring property.

.substrings v2.0.5

See Selection object’s substrings property.

.substringCount v2.0.5

See Selection object’s substringCount property.

.firstAttributes v3.0.2

See Selection object’s firstAttributes property.

.firstDisplayAttributes v3.0.2

See Selection object’s firstDisplayAttributes property.

.typingAttributes v1.2

See Selection object’s typingAttributes property.

.displayTypingAttributes v1.2

See Selection object’s displayTypingAttributes property.

.characterStyle v2.0.5

See Selection object’s characterStyle property.

.paragraphStyle v2.0.5

See Selection object’s paragraphStyle property.

.listStyle v2.0.5

See Selection object’s listStyle property.

.noteStyle v2.0.5

See Selection object’s noteStyle property.

.tables v2.0.5

See Selection object’s tables property.

.enclosedTables v2.0.5

See Selection object’s enclosedTables property.

.inlineImage v2.0.5

See Selection object’s inlineImage property.

.inlineImages v2.0.5

See Selection object’s inlineImages property.

.enclosedInlineImages v2.0.5

See Selection object’s enclosedInlineImages property.

.floatingContent v2.0.5

See Selection object’s floatingContent property.

.floatingContents v2.0.5

See Selection object’s floatingContents property.

.enclosedFloatingContents v2.0.5

See Selection object’s enclosedFloatingContents property.

TextSelection Object Commands

.containsSelection otherTextSelection v1.3

Returns @true if both selections are over the same Text object and the other selection’s range is completely contained, otherwise @false.

.intersectsSelection otherTextSelection v1.3

Returns @true if both selections are over the same Text object and the selected ranges intersect, otherwise @false.

.intersectionSelection otherTextSelection v1.3

If both selections are over the same Text object and the selected ranges intersect, returns a new TextSelection object that describes their intersection, otherwise the @undefined value.

.unionSelection otherTextSelection v1.3

If both selections are over the same Text object, returns a new TextSelection object that describes their union, otherwise the @undefined value.

.unionContiguousSelection otherTextSelection v2.0.5

If both selections are over the same Text object, and the ranges either overlap or exactly touch (so that the union does not include any additional annexed characters), then returns a new TextSelection object that describes their union, otherwise the @undefined value.

.unionKissingSelection otherTextSelection v2.0.5

If both selections are over the same Text object, and the endpoint of one selection’s range exactly touches (but does not overlap) the starting point of another selection’s range, then returns a new TextSelection object that describes their union, otherwise the @undefined value.

TextSelection Object Examples

The following code selects all text in the active document’s body:

$text = TextSelection.activeText

$allRange = Range.new(0, $text.length)

TextSelection.setActiveRange($allRange)

The following code is another way to select all text in the active document’s body:

$doc = Document.active

$text = $doc.text

$allRange = Range.new(0, $text.length)

$selection = TextSelection.new($text, $allRange)

$doc.setSelection($selection)

The following (not very useful) macro selects every 10th character in the document:

$doc = Document.active

$text = $doc.text

$selections = Array.new

$characterIndex = 0

While $characterIndex < $text.length

$range = Range.new($characterIndex, 1)

$selection = TextSelection.new($text, $range)

$selections.appendValue($selection)

$characterIndex += 10

End

$doc.setSelections($selections)