Text Object - Formatting & Layout

The following Text object commands provide ways to access formatting and layout information for a text object.

.attributesAtIndex charIndex, [range] v1.1

Returns an Attributes object describing the formatting applied at the given character index in the text. The returned attributes object will only have properties defined for those values that have been explicitly applied to the character.

As an example, consider a document that has a Normal paragraph style that defines the font to be 12 point Copperplate. If a piece of text in this document has only the Normal paragraph style applied (eg: the text displays in 12 point Copperplate) then the attributes returned will have the @undefined value for both the fontSize and fontName property.

However, if the user changed the font size of the text in the document so it displays in 14 point Copperplate, then the fontSize property would be 14.0, while the fontName property remains @undefined. In other words, the returned attributes describe the manually applied formatting, ignoring those defined by styles.

The optional range argument should be a Range object. Upon return it will be set to the range of characters over which the attributes are applied, as described in the rangeOfAttributesAtIndex command below. This argument was added in v3.0.

See also: displayAttributesAtIndex below.

.rangeOfAttributesAtIndex charIndex v1.1

Returns a Range object that specifies over which characters the attributes at the given index are guaranteed to be equal. This range is not necessarily the longest (maximal) range over which attributes are equal, eg: text adjacent to the returned range could have the same attributes. The returned range will always contain the given index and be non-zero in length.

As an example, consider the text “bold plain”. The range returned at index zero could have location 0 and length 4, because the bold property changes values at the space character. However, it is just as possible this command could return a range with location 0 and length 2. In general attempts are made to not break runs of equal attributes up like this, but it is always a possibility and no assumptions should be made.

See also: rangeOfDisplayAttributesAtIndex below.

.displayAttributesAtIndex charIndex, [range] v1.1

Returns an Attributes object describing the formatting used to display the character at the given index in the text. This value differs from that returned by the attributesAtIndex command because formatting defined by styles applied to the text will be considered.

As an example, again consider the document whose Normal paragraph style is 12 point Copperplate. If a piece of text in this document has only the Normal paragraph style applied (eg: the text displays in 12 point Copperplate) then the display attributes returned will have a fontSize property of 12.0 and a fontName property of ‘Copperplate’.

In addition to the effects of styles, display attributes also take into account other kinds of processing required for display. One example is font substitution. If the Tahoma font had been applied to some Hebrew letters it would be necessary to use another font to actually display those letters. The actual font used to display those letters will be reported by the display attributes, while Tahoma would be reported by attributesAtIndex. 

In general display attribute properties are never @undefined unless they are explicitly documented to return that value under certain circumstances.

The optional range argument should be a Range object. Upon return it will be set to the range of characters over which the attributes are applied, as described in the rangeOfDisplayAttributesAtIndex command below. This argument was added in v3.0.

.rangeOfDisplayAttributesAtIndex charIndex v1.1

Operates exactly as the rangeOfAttributesAtIndex command, except that the returned Range object describes characters over which the display attributes (as defined by the command displayAttributesAtIndex) are guaranteed to be equal. 

Note that the range of display attributes can be different than the range reported by rangeOfAttributesAtIndex.

.sectionNumberAtIndex charIndex v1.3

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

.rangeOfSectionAtIndex charIndex v1.1

Returns a Range object that specifies over which characters the document section is effective. The argument given to this command is a character index which the returned range will include. The returned range always covers all the characters that are included in the section. 

If this command is used on a non-document text object that has no sections (eg: a plain string), the returned range will cover all characters in the text.

.lineNumberAtIndex charIndex, [isLogical] v1.3

Returns a Range object that specifies which characters are laid out on a single line when printed on the page. In other words, the line range contains all characters that fit on a single line in Page View without wrapping. 

If the text object is not part of a document, this command returns the @undefined value. The given index must be in-bounds or an error will be displayed.

.rangeOfBlockAtIndex charIndex v1.3

Returns a Range object that specifies which characters are laid out in a single contiguous block on a single page, when printed or displayed in Page View.

For the main document body this range simply contains all characters on a single page. However, for other text objects the range can be different. For example, the block range for a table cell would be limited to the characters in that cell. If the cell spans multiple pages, the range would be those characters in the cell that fit on a single page.

If the text object is not part of a document, this command returns the @undefined value. The given index must be in-bounds or an error will be displayed.

.pageNumberAtIndex charIndex, [isLogical] v1.3

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

The isLogical argument works just as in the command lineNumberAtIndex above.

.rangeOfPageAtIndex charIndex v2.1

Returns a Range object that specifies which characters are laid out on a single page when printed. In other words, the returned range contains all characters that fit on a single page in Page View.

If the text object is not part of a document, this command returns the @undefined value. The given index must be in-bounds or an error will be displayed.

.boundingSizeInRange rangeValue v3.2

Returns a Size object for the enclosing dimensions (in points) of the characters within the given Range object. This takes into account how text has wrapped between lines in Page View. The returned size may be taller than expected if the text shares a line with larger content. Use opticalSizeInRange for more precise measurements.

.opticalSizeInRange rangeValue v3.2

Returns a Size object for the enclosing dimensions (in points) of all visible markings made by characters within the given Range object. This takes into account how text has wrapped between lines in Page View.

NOTE: this can be expensive to calculate and using this command repeatedly or on large amounts of text may be slow.