Text Object - Basic Commands

Returns a new text object that only contains the specified portion of the existing text object. The Range object must be in-bounds or an error will be displayed.

.subtextFromIndex startIndex v3.1

Returns a new text object that contains only characters from the given character index (including that character) to the end of the existing text object. The index must be in-bounds or an error will be displayed, but can be equal to the length of the existing text object, in which case an empty text object is returned.

.subtextToIndex boundIndex v3.1

Returns a new text object that contains only characters from the start of the existing text object up to, but not including, the given boundary index. The index must be in-bounds or an error will be displayed, but can be equal to the length of the existing text object.

.substringInRange rangeObject v1.3

Returns a new plain text string that only contains the specified portion of the existing text object, discarding any attributes and special content. The Range object must be in-bounds or an error will be displayed.

.compare otherText, [options], [language] v1.1

The optional language argument is a Language object that specifies what localization rules should be considered in the comparison. The language only has any effect if the comparison mode is set to localized and the user is running on OSX 10.5 (Leopard) or later. This argument was added in v1.3.

.characterAtIndex charIndex v1.1

Returns the numeric (decimal) value of the character at the given index, which must be in-bounds or an error will be displayed. This number is the Unicode code point of the character, eg: ‘∂’ returns 8,706 (U+2202).

Note: the return value is actually the 16 bit number used in the UTF-16 encoding, eg: for characters above U+FFFF the value returned may be part of a surrogate pair. This is uncommon (see the length property above for more).

Starting with v2.1 you may directly compare a character value with a single-character string, eg:

$text = "hello!"

If "h" == $text.characterAtIndex(0)

.rangeOfComposedCharacterAtIndex charIndex v1.3

Returns a Range object that specifies which characters at the given index are combined together to form one character combined for display purposed. The index must be in-bounds or an error will be displayed.

The returned range will cover the base character and any combining marks that may follow it, eg: an “x” followed by a combining over line mark (U+0305) displays as a single character to the user as “x̅” but is actually represented as two underlying Unicode characters.

.codepointAtIndex charIndex, [effectiveRange] v2.0.5

Returns the integer value of the Unicode code point at the given character index. If provided, the given Range object will be modified so that upon returning it will specify the effective range of the returned code point.

An example that iterates all code points in a string:

$text = "Hello"

$codeRange = Range.new

$limit = $text.length

$charIndex = 0

While $charIndex < $limit

$code = $text.codepointAtIndex($charIndex, $codeRange)

Prompt "Code point is $code"

$charIndex = $codeRange.bound

End

.codepointStrings v2.0.5

Returns an array of strings, where each Unicode code point in the text has been converted to a hexadecimal description. Note: this command is not efficient, but is useful primarily for debugging and inspection of text.

.rangeOfSentenceAtIndex charIndex v2.0

Returns a Range object that specifies which characters (including the terminal) form a single sentence at the given index, which must be in-bounds or an error will be displayed. 

The first index in the returned range is the first character following the prior sentence terminal (eg: a period) or grouping punctuation (eg: a closing quote mark). The last index included is the sentence terminal or the closing grouping punctuation mark following it.

.paragraphNumberAtIndex charIndex v1.3

Returns the paragraph number of the character at the given index, which must be in-bounds or an error will be displayed. A paragraph number is 1-based and never restarts. If the text object is not part of a document, this command returns the @undefined value.

.rangeOfParagraphAtIndex charIndex v1.3

Returns a Range object that specifies which characters (including the newline) form a single paragraph at the given index, which must be in-bounds or an error will be displayed. 

The first index in the returned range is the first character in the paragraph, and the last index is the line break character that terminates the paragraph, if one exists (the last paragraph in any text object may not have such a break character). The returned range thus always includes the given index and will never be zero length.

.rangeOfParagraphContentAtIndex charIndex v1.3

Returns a Range object that specifies which characters (excluding the line break) form a single paragraph at the given index, which must be in-bounds or an error will be displayed. 

The first index in the returned range is the first character in the paragraph, while the last index is that of the character directly preceding the line break that terminates the paragraph. If the paragraph contains no text, the returned range may be zero length. Also, if the given index is that of the line break character itself, the returned range may not contain the given index.

.breakTypeAtIndex charIndex v2.0.5

Returns a string describing what kind of break is enforced by the given character. The possible return values are as follows:

.flashInRange charRange, [color], [speed] v2.0.5

A Color object may be provided to choose the flash’s color, otherwise the user’s set flash color is used. The speed is a factor applied to how fast the animation progresses. So a value of 1.0 will show the flash using the normal duration, while a value of 2.0 would animate twice as fast.

Note: the given range is never adjusted for edits that occur to the text, so if your macro makes subsequent changes the flashed character range may not be as intended. Also, because running macros intermittently make exclusive use of the application, a flash will not animate smoothly while a macro is in progress. For both of these reasons it is probably best to flash text at the very end of your macro, to show the user where changes occurred.