---

NSParagraphStyle

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.

Tasks

Constructors

• NSParagraphStyle

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

Static Methods

defaultParagraphStyle

Returns the default paragraph style.

public static NSParagraphStyle defaultParagraphStyle()

Discussion

The default paragraph style has the following default values:

See individual method descriptions for explanations of each subattribute.

defaultWritingDirectionForLanguage

Returns the default writing direction for languageName.

public static int defaultWritingDirectionForLanguage(String languageName)

Discussion

languageName is in ISO language region format. Possible return values are described in “Constants.”

Availability

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

See Also

• baseWritingDirection
• setBaseWritingDirection (NSMutableParagraphStyle)

Instance Methods

alignment

Returns the text alignment of the receiver.

public int alignment()

Discussion

Text alignment is one of:

• NSText.LeftTextAlignment

• NSText.RightTextAlignment

• NSText.CenterTextAlignment

• NSText.JustifiedTextAlignment

• NSText.NaturalTextAlignment

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

See Also

• setAlignment (NSMutableParagraphStyle)

baseWritingDirection

Returns the base writing direction for the receiver. Possible return values are described in “Constants.”

public int baseWritingDirection()

Availability

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

See Also

• defaultWritingDirectionForLanguage
• setBaseWritingDirection (NSMutableParagraphStyle)

defaultTabInterval

Returns the document-wide default tab interval.

public float defaultTabInterval()

Discussion

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)

firstLineHeadIndent

Returns the distance in points from the leading margin of a text container to the beginning of the paragraph’s first line.

public float firstLineHeadIndent()

Discussion

This value is always nonnegative.

See Also

• headIndent
• tailIndent
• setFirstLineHeadIndent (NSMutableParagraphStyle)

headerLevel

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

public int headerLevel()

Discussion

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)

headIndent

Returns the distance in points from the leading margin of a text container to the beginning of lines other than the first.

public float headIndent()

Discussion

This value is always nonnegative.

See Also

• firstLineHeadIndent
• tailIndent
• setHeadIndent (NSMutableParagraphStyle)

hyphenationFactor

Returns the paragraph’s threshold for hyphenation.

public float hyphenationFactor()

Discussion

Valid values lie between 0.0 and 1.0 inclusive. The default value is 0.0. 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)

lineBreakMode

Returns the mode that should be used to break lines when laying out the paragraph’s text.

public int lineBreakMode()

Discussion

See “Constants” for a list of values.

See Also

• setLineBreakMode (NSMutableParagraphStyle)

lineHeightMultiple

Returns the line height multiple.

public float lineHeightMultiple()

Discussion

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)

lineSpacing

Returns the space in points added between lines within the paragraph (commonly known as leading).

public float lineSpacing()

Discussion

This value is always nonnegative.

See Also

• maximumLineHeight
• minimumLineHeight
• paragraphSpacing
• setLineSpacing (NSMutableParagraphStyle)

maximumLineHeight

Returns the maximum height that any line in the receiver will occupy, regardless of the font size or size of any attached graphic.

public float maximumLineHeight()

Discussion

Glyphs and graphics exceeding this height will overlap neighboring lines; however, a maximum height of 0 implies no line height limit. This value is always nonnegative. The default value is 0.

Although this limit applies to the line itself, line spacing adds extra space between adjacent lines.

See Also

• minimumLineHeight
• lineSpacing
• lineHeightMultiple
• setMaximumLineHeight (NSMutableParagraphStyle)

minimumLineHeight

Returns the minimum height that any line in the receiver will occupy, regardless of the font size or size of any attached graphic.

public float minimumLineHeight()

Discussion

This value is always nonnegative.

See Also

• maximumLineHeight
• lineSpacing
• lineHeightMultiple
• setMinimumLineHeight (NSMutableParagraphStyle)

paragraphSpacing

Returns the space added at the end of the paragraph to separate it from the following paragraph.

public float paragraphSpacing()

Discussion

This value is always nonnegative. Determined by adding the previous paragraph’s paragraphSpacing and the current paragraph’s paragraphSpacingBefore.

See Also

• lineSpacing
• setParagraphSpacing (NSMutableParagraphStyle)

paragraphSpacingBefore

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

public float paragraphSpacingBefore()

Discussion

Default return value is 0.0.

Availability

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

See Also

• paragraphSpacing
• setParagraphSpacingBefore (NSMutableParagraphStyle)

tabStops

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

public NSArray tabStops()

See Also

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

tailIndent

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

public float tailIndent()

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.

See Also

• headIndent
• firstLineHeadIndent
• setTailIndent (NSMutableParagraphStyle)

textBlocks

Returns an array specifying the text blocks containing the paragraph, nested from outermost to innermost.

public NSArray textBlocks()

Availability

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

See Also

• setTextBlocks (NSMutableParagraphStyle)

textLists

Returns an array specifying the text lists containing the paragraph, nested from outermost to innermost.

public NSArray textLists()

Availability

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

See Also

• setTextLists (NSMutableParagraphStyle)

tighteningFactorForTruncation

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

public float tighteningFactorForTruncation()

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. The default value is 0.05.

Availability

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

See Also

• setTighteningFactorForTruncation (NSMutableParagraphStyle)

Constants

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

These constants specify the types of tab stops:

These constants specify the writing directions:

---