NSParagraphStyle Class Reference

Overview

NSParagraphStyle and its subclass NSMutableParagraphStyle encapsulate the paragraph or ruler attributes used by the NSAttributedString classes. Instances of these classes are often referred to as paragraph style objects or, when no confusion will result, paragraph styles.

The mutable subclass of NSParagraphStyle is NSMutableParagraphStyle.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

• – copyWithZone:

• – mutableCopyWithZone:

Tasks

Creating an NSParagraphStyle

• + defaultParagraphStyle

Accessing Style Information

• – alignment
• – firstLineHeadIndent
• – headIndent
• – tailIndent
• – tabStops
• – defaultTabInterval
• – lineHeightMultiple
• – maximumLineHeight
• – minimumLineHeight
• – lineSpacing
• – paragraphSpacing
• – paragraphSpacingBefore

Getting Text Block and List Information

• – textBlocks
• – textLists

Getting Line Breaking Information

• – lineBreakMode
• – hyphenationFactor
• – tighteningFactorForTruncation

Getting HTML Header Level

• – headerLevel

Writing Direction

• + defaultWritingDirectionForLanguage:
• – baseWritingDirection

Class Methods

defaultParagraphStyle

Returns the default paragraph style.

+ (NSParagraphStyle *)defaultParagraphStyle

Discussion

The default paragraph style has the following default values:

See individual method descriptions for explanations of each subattribute.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• FilterDemo
• iSpend
• PhotoSearch
• Quartz Composer WWDC 2005 TextEdit
• TipWrapper

Declared In

NSParagraphStyle.h

defaultWritingDirectionForLanguage:

Returns the default writing direction for the specified language.

+ (NSWritingDirection)defaultWritingDirectionForLanguage:(NSString *)languageName

Parameters

languageName

The language specified in ISO language region format. Can be nil to return a default writing direction derived from the user’s defaults database.

Return Value

The default writing direction.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – baseWritingDirection
• – setBaseWritingDirection: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

Instance Methods

alignment

Returns the text alignment of the receiver.

- (NSTextAlignment)alignment

Return Value

The text alignment.

Discussion

Natural text alignment is realized as left or right alignment depending on the line sweep direction of the first script contained in the paragraph.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAlignment: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

baseWritingDirection

Returns the base writing direction for the receiver.

- (NSWritingDirection)baseWritingDirection

Return Value

The base writing direction for the receiver.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + defaultWritingDirectionForLanguage:
• – setBaseWritingDirection: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

defaultTabInterval

Returns the document-wide default tab interval.

- (CGFloat)defaultTabInterval

Return Value

The default tab interval in points. Tabs after the last specified in tabStops are placed at integer multiples of this distance (if positive). Default return value is 0.0.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setDefaultTabInterval: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

firstLineHeadIndent

Returns the indentation of the first line of the receiver.

- (CGFloat)firstLineHeadIndent

Return Value

The distance in points from the leading margin of a text container to the beginning of the paragraph’s first line. This value is always nonnegative.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – headIndent
• – tailIndent
• – setFirstLineHeadIndent: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

headerLevel

Specifies whether the paragraph is to be treated as a header for purposes of HTML generation.

- (NSInteger)headerLevel

Return Value

Returns 0 (the default value), if the paragraph is not a header, or from 1 through 6 if the paragraph is to be treated as a header.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setHeaderLevel: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

headIndent

Returns the indentation of the receiver’s lines other than the first.

- (CGFloat)headIndent

Return Value

The distance in points from the leading margin of a text container to the beginning of lines other than the first. This value is always nonnegative.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – firstLineHeadIndent
• – tailIndent
• – setHeadIndent: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

hyphenationFactor

Returns the paragraph’s threshold for hyphenation.

- (float)hyphenationFactor

Return Value

A value between 0.0 and 1.0 inclusive. The default value is 0.0.

Discussion

Hyphenation is attempted when the ratio of the text width (as broken without hyphenation) to the width of the line fragment is less than the hyphenation factor. When the paragraph’s hyphenation factor is 0.0, the layout manager’s hyphenation factor is used instead. When both are 0.0, hyphenation is disabled.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setHyphenationFactor: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

lineBreakMode

Returns the mode that should be used to break lines in the receiver.

- (NSLineBreakMode)lineBreakMode

Return Value

The line break mode to be used laying out the paragraph’s text.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setLineBreakMode: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

lineHeightMultiple

Returns the line height multiple.

- (CGFloat)lineHeightMultiple

Return Value

The line height multiple. The natural line height of the receiver is multiplied by this factor (if positive) before being constrained by minimum and maximum line height. Default return value is 0.0.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – maximumLineHeight
• – minimumLineHeight
• – setLineHeightMultiple: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

lineSpacing

Returns the space between lines in the receiver (commonly known as leading).

- (CGFloat)lineSpacing

Return Value

The space in points added between lines within the paragraph. This value is always nonnegative.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – maximumLineHeight
• – minimumLineHeight
• – paragraphSpacing
• – setLineSpacing: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

maximumLineHeight

Returns the receiver’s maximum line height.

- (CGFloat)maximumLineHeight

Return Value

The maximum height in points that any line in the receiver will occupy, regardless of the font size or size of any attached graphic. This value is always nonnegative. The default value is 0.

Discussion

Glyphs and graphics exceeding this height will overlap neighboring lines; however, a maximum height of 0 implies no line height limit. Although this limit applies to the line itself, line spacing adds extra space between adjacent lines.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – minimumLineHeight
• – lineSpacing
• – lineHeightMultiple
• – setMaximumLineHeight: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

minimumLineHeight

Returns the receiver’s minimum height.

- (CGFloat)minimumLineHeight

Return Value

The minimum height in points that any line in the receiver will occupy, regardless of the font size or size of any attached graphic. This value is always nonnegative.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – maximumLineHeight
• – lineSpacing
• – lineHeightMultiple
• – setMinimumLineHeight: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

paragraphSpacing

Returns the space after the end of the paragraph.

- (CGFloat)paragraphSpacing

Return Value

The space in points added at the end of the paragraph to separate it from the following paragraph. This value is always nonnegative.

Discussion

This value is determined by adding the previous paragraph’s paragraphSpacing and the current paragraph’s paragraphSpacingBefore.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – lineSpacing
• – paragraphSpacingBefore
• – setParagraphSpacing: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

paragraphSpacingBefore

Returns the distance between the paragraph’s top and the beginning of its text content.

- (CGFloat)paragraphSpacingBefore

Return Value

The distance in points between the paragraph’s top and the beginning of its text content. Default return value is 0.0.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – paragraphSpacing
• – setParagraphSpacingBefore: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

tabStops

Returns the receiver’s tab stops.

- (NSArray *)tabStops

Return Value

The NSTextTab objects, sorted by location, that define the tab stops for the paragraph style.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – location (NSTextTab)
• – setTabStops: (NSMutableParagraphStyle)
• – addTabStop: (NSMutableParagraphStyle)
• – removeTabStop: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

tailIndent

Returns the trailing indentation of the receiver.

- (CGFloat)tailIndent

Return Value

The distance in points from the margin of a text container to the end of lines.

Discussion

If positive, this value is the distance from the leading margin (for example, the left margin in left-to-right text). If 0 or negative, it’s the distance from the trailing margin.

For example, a paragraph style designed to fit exactly in a 2-inch wide container has a head indent of 0.0 and a tail indent of 0.0. One designed to fit with a quarter-inch margin has a head indent of 0.25 and a tail indent of –0.25.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – headIndent
• – firstLineHeadIndent
• – setTailIndent: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

textBlocks

Returns an array specifying the text blocks containing the paragraph.

- (NSArray *)textBlocks

Return Value

An array of the NSTextTableBlock objects containing the paragraph, nested from outermost to innermost.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setTextBlocks: (NSMutableParagraphStyle)

Related Sample Code

• iSpend

Declared In

NSParagraphStyle.h

textLists

Returns an array specifying the text lists containing the paragraph.

- (NSArray *)textLists

Return Value

An array of the NSTextList objects containing the paragraph, nested from outermost to innermost.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setTextLists: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

tighteningFactorForTruncation

Returns the threshold for using tightening as an alternative to truncation.

- (float)tighteningFactorForTruncation

Return Value

The tightening threshold value. The default value is 0.05.

Discussion

When the line break mode specifies truncation, the text system attempts to tighten intercharacter spacing as an alternative to truncation, provided that the ratio of the text width to the line fragment width does not exceed 1.0 + the tightening factor returned by this method. Otherwise the text is truncated at a location determined by the line break mode.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setTighteningFactorForTruncation: (NSMutableParagraphStyle)

Declared In

NSParagraphStyle.h

Constants

NSLineBreakMode

These constants specify what happens when a line is too long for its container.

typedef enum _NSLineBreakMode {
   NSLineBreakByWordWrapping = 0,
   NSLineBreakByCharWrapping,
   NSLineBreakByClipping,
   NSLineBreakByTruncatingHead,
   NSLineBreakByTruncatingTail,
   NSLineBreakByTruncatingMiddle
} NSLineBreakMode;

Constants

NSLineBreakByWordWrapping

Wrapping occurs at word boundaries, unless the word itself doesn’t fit on a single line.

Available in Mac OS X v10.0 and later.

Declared in NSParagraphStyle.h.

NSLineBreakByCharWrapping

Wrapping occurs before the first character that doesn’t fit.

Available in Mac OS X v10.0 and later.

Declared in NSParagraphStyle.h.

NSLineBreakByClipping

Lines are simply not drawn past the edge of the text container.

Available in Mac OS X v10.0 and later.

Declared in NSParagraphStyle.h.

NSLineBreakByTruncatingHead

Each line is displayed so that the end fits in the container and the missing text is indicated by some kind of ellipsis glyph.

Available in Mac OS X v10.0 and later.

Declared in NSParagraphStyle.h.

NSLineBreakByTruncatingTail

Each line is displayed so that the beginning fits in the container and the missing text is indicated by some kind of ellipsis glyph.

Available in Mac OS X v10.0 and later.

Declared in NSParagraphStyle.h.

NSLineBreakByTruncatingMiddle

Each line is displayed so that the beginning and end fit in the container and the missing text is indicated by some kind of ellipsis glyph in the middle.

Available in Mac OS X v10.0 and later.

Declared in NSParagraphStyle.h.

Declared In

NSParagraphStyle.h

NSTextTabType

These constants specify the types of tab stops.

typedef enum _NSTextTabType {
   NSLeftTabStopType = 0,
   NSRightTabStopType,
   NSCenterTabStopType,
   NSDecimalTabStopType
} NSTextTabType;

Constants

NSLeftTabStopType

A left-aligned tab stop.

Available in Mac OS X v10.0 and later.

Declared in NSParagraphStyle.h.

NSRightTabStopType

A right-aligned tab stop.

Available in Mac OS X v10.0 and later.

Declared in NSParagraphStyle.h.

NSCenterTabStopType

A center-aligned tab stop.

Available in Mac OS X v10.0 and later.

Declared in NSParagraphStyle.h.

NSDecimalTabStopType

Aligns columns of numbers by the decimal point.

Available in Mac OS X v10.0 and later.

Declared in NSParagraphStyle.h.

Declared In

NSParagraphStyle.h

---