NSTextList Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.4 and later.
Declared in
NSTextList.h

Overview

An NSTextList object represents a section of text that forms a single list. The visible elements of the list, including list markers, appear in the text as they do for lists created by hand. The list object, however, allows the list to be recognized as such by the text system. This enables automatic creation of markers and spacing. Text lists are used in HTML import and export.

Text lists appear as attributes on paragraphs, as part of the paragraph style. An NSParagraphStyle may have an array of text lists, representing the nested lists containing the paragraph, in order from outermost to innermost. For example, if list1 contains four paragraphs, the middle two of which are also in the inner list2, then the text lists array for the first and fourth paragraphs is (list1), while the text lists array for the second and third paragraphs is (list1, list2).

The methods implementing this are textLists on NSParagraphStyle, and setTextLists: on NSMutableParagraphStyle.

In addition, NSAttributedString has convenience methods for lists:rangeOfTextList:atIndex:, which determines the range covered by a list, and itemNumberInTextList:atIndex:, which determines the ordinal position within a list of a particular item.

Tasks

Creating a Text List

Working with Markers

Getting List Options

Managing Item Numbering

Instance Methods

initWithMarkerFormat:options:

Returns an initialized text list.

- (id)initWithMarkerFormat:(NSString *)format options:(NSUInteger)mask
Parameters
format

The marker format for the text list.

mask

The marker options for the text list. Values for mask are listed in “Constants.”

Return Value

An initialized text list.

Discussion

The marker format is specified as a constant string, except for a numbering specifier, which takes the form {keyword}. The currently supported values for keyword include:

  • box

  • check

  • circle

  • diamond

  • disc

  • hyphen

  • square

  • lower-hexadecimal

  • upper-hexadecimal

  • octal

  • lower-alpha or lower-latin

  • upper-alpha or upper-latin

  • lower-roman

  • upper-roman

  • decimal

Thus, for example, @"({decimal})" would specify the format for a list numbered (1), (2), (3), and so on, and @"{upper-roman}" would specify the format for a list numbered I, II, III, IV, and so on. (All of these keywords are included in the Cascading Style Sheets level 3 specification.)

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTextList.h

listOptions

Returns the list options mask value of the receiver.

- (NSUInteger)listOptions
Return Value

The list options mask value of the receiver.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTextList.h

markerForItemNumber:

Returns the computed value for a specific ordinal position in the list.

- (NSString *)markerForItemNumber:(NSInteger)itemNum
Parameters
itemNum

The ordinal position in the list whose computed marker value is desired.

Return Value

The computed maker value for itemNum.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTextList.h

markerFormat

Returns the marker format string used by the receiver.

- (NSString *)markerFormat
Return Value

The marker format string used by the receiver.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTextList.h

setStartingItemNumber:

Sets the starting item number for the text list.

- (void)setStartingItemNumber:(NSInteger)itemNum
Parameters
itemNum

The item number.

Discussion

The default value is 1. This value will be used only for ordered lists, and ignored in other cases.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextList.h

startingItemNumber

Returns the starting item number for the text list.

- (NSInteger)startingItemNumber
Return Value

The item number.

Discussion

The default value is 1. This value will be used only for ordered lists, and ignored in other cases.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextList.h

Constants

The following constant specifies an option mask used with initWithMarkerFormat:options:.

Constant

Description

NSTextListPrependEnclosingMarker

Specifies that a nested list should include the marker for its enclosing superlist before its own marker.

Available in OS X v10.4 and later.

Declared in NSTextList.h.