ListItem Object

A ListItem object represents a single list item (or list bullet) in a Text object, as automatically generated and configured by an applied list style. ListItem objects can be retrieved using a variety of ListItem Type Commands (see below).

If you obtain a ListItem object and its original text is deleted, then accessing the list item displays an error. For example:

$item = ListItem.activeItem

Select All

Delete

$level = $item.level # list item is gone; shows an error

ListItem Type Commands

Returns an Array of all ListItem objects selected in the active document. If no list items are selected, the returned array is empty.

ListItem.itemInTextAtIndex text, charIndex, [effectiveRange] v2.1.2

Returns a ListItem object for the list item at the given character index in the given Text. If the specified character is not exactly part of a list item, returns the @undefined value.

If provided, the given Range object will be modified so that upon returning it will specify the effective range of the returned list item. If no list item exists at the given character, this range is set to some range over which it is known that no list item exists.

ListItem.itemInTextInParagraphAtIndex text, charIndex, [effectiveRange] v2.1.2

Returns a ListItem object for the list item at the start of the paragraph containing the given character index in the given Text. That is, the given character index can be any character in the paragraph, and the list item for that paragraph will still be returned. If the paragraph has no list item, returns the @undefined value.

If provided, the given Range object will be modified so that upon returning it will specify the effective range of the returned list item. If no list item exists at the given character, this range is set to some range over which it is known that no list item exists.

ListItem.itemsInTextInRange text, range v2.1.2

Returns an Array of all ListItem objects intersecting the given character Range in the given Text. If no list items intersect the given range, returns an empty array.

ListItem.itemsIn content v2.1.2

Returns an Array of all ListItem objects contained inside the given content or selection object, which may be a Document, Selection, Text, Table, TableCell, Note, FloatingContent, or an array holding some combination thereof. If the given content contains no list items, returns an empty array.

ListItem Properties & Commands

.enclosingText v2.1.2

Returns the Text object in which this list item resides. Read-only.

Note: the returned text object follows reference semantics and holds the entire text area (eg: the whole document body, whole text cell, etc). Changes to the returned text will change the contents of the document itself.

.enclosingTextRange v2.1.2

Returns the Range object representing the list item’s characters within its enclosingText object. This range includes the list item’s tab character (and any other special control characters). Read-only.

.subtext v2.1.2

Returns a new Text object that contains just the list item. This content does not include any tabs that may follow the list item’s text. Modifications to the returned text object will not be reflected in the corresponding document, nor can you use this text object to generate new document selections. Read-only.

.substring v2.1.2

This functions just like subtext, but returns a plain text string of the text. Read-only.

.style v2.1.2

Returns the Style object for the list style (as applied in the text) that generated the list item. Read-only.

.styleName v2.1.2

Returns the name of the list style (as applied in the text) that generated the list item. Read-only.

.level v2.1.2

Returns the effective listing level for the list item. The first level is 1, and increases for each listing indentation. Read-only.

.number v2.1.2

Returns the number of the list item, as determined by the sequence of list items in the document and any applied options. For example, this number takes into account any numbering restarts, as manually set by the user or automatically triggered due to gaps in the applied list style in the document. Read-only.

For list items that show numbering for more than a single listing level (eg: the Tiered List style), the returned number is that of the innermost (highest) listing level. 

An example list:

1. Dogs

2. Cats

2.a. Bobcat

2.b. Lion

2.c. Lynx

The returned numbers for these list items are 1, 2, 1, 2, and 3 respectively.

.numbers v2.1.2

Returns an Array of all listing numbers for the list item, one for each listing level displayed by the item, as determined by the sequence of list items in the document and any applied options. Read-only.

For example, if a list item is displayed as “1.1.3” the returned array is (1, 1, 3). List items displaying only a single level return an array with one value, eg: the list item “b.” returns the array (2).

.numberForLevel level v2.1.2

Returns the number displayed by the list item for the given listing level. The first level is 1 and increases for each listing indentation. If the given level is not displayed by the list item, returns the undefined value. Read-only.

For example, if a list item is displayed as “2.c.” then the number returned for level 2 is 3.

.subtextForLevel level v2.1.2

This functions just like subtextForLevel, but returns a plain text string of the text. Read-only.