---

NSLayoutManager Class Reference

Overview

An NSLayoutManager object coordinates the layout and display of characters held in an NSTextStorage object. It maps Unicode character codes to glyphs, sets the glyphs in a series of NSTextContainer objects, and displays them in a series of NSTextView objects. In addition to its core function of laying out text, an NSLayoutManager object coordinates its NSTextView objects, provides services to those text views to support NSRulerView instances for editing paragraph styles, and handles the layout and display of text attributes not inherent in glyphs (such as underline or strikethrough). You can create a subclass of NSLayoutManager to handle additional text attributes, whether inherent or not.

Text Antialiasing

NSLayoutManager provides the threshold for text antialiasing. It looks at the AppleAntiAliasingThreshold default value. If the font size is smaller than or equal to this threshold size, the text is rendered aliased by NSLayoutManager. You can change the threshold value from the Appearance pane of System Preferences.

Thread Safety of NSLayoutManager

Generally speaking, a given layout manager (and associated objects) should not be used on more than one thread at a time. Most layout managers are used on the main thread, since it is the main thread on which their text views are displayed, and since background layout occurs on the main thread. If it is intended that a layout manager should be used on a background thread, first make sure that text views associated with that layout manager (if any) are not displayed while the layout manager is being used on the background thread, and, second, turn off background layout for that layout manager while it is being used on the background thread.

Noncontiguous Layout

Noncontiguous layout is an optional layout manager behavior new in Mac OS X v10.5. Previously, both glyph generation and layout were always performed, in order, from the beginning to the end of the document. When noncontiguous layout is turned on, however, the layout manager gains the option of performing glyph generation or layout for one portion of the document without having done so for previous sections. This can provide significant performance improvements for large documents.

Noncontiguous layout is not turned on automatically because direct clients of NSLayoutManager typically have relied on the previous behavior—for example, by forcing layout for a given glyph range, and then assuming that previous glyphs would therefore be laid out. Clients who use NSLayoutManager only indirectly—for example, those who use NSTextView without directly calling the underlying layout manager—can usually turn on noncontiguous layout without difficulty. Clients using NSLayoutManager directly need to examine their usage before turning on noncontiguous layout.

To turn on noncontiguous layout, use setAllowsNonContiguousLayout:. In addition, see the other methods in “Managing Noncontiguous Layout,” many of which enable you to ensure that glyph generation and layout are performed for specified portions of the text. The behavior of a number of other layout manager methods is affected by the state of noncontiguous layout, as noted in the discussion sections of those method descriptions.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

• – attributedString

• – insertGlyphs:length:forStartingGlyphAtIndex:characterIndex:

• – layoutOptions

• – setIntAttribute:value:forGlyphAtIndex:

Tasks

Initializing

• – init

Setting the Text Storage

• – setTextStorage:
• – textStorage
• – replaceTextStorage:

Setting Text Containers

• – textContainers
• – addTextContainer:
• – insertTextContainer:atIndex:
• – removeTextContainerAtIndex:

Setting the Glyph Generator

• – setGlyphGenerator:
• – glyphGenerator

Invalidating Glyphs and Layout

• – invalidateGlyphsForCharacterRange:changeInLength:actualCharacterRange:
• – invalidateGlyphsOnLayoutInvalidationForGlyphRange:
• – invalidateLayoutForCharacterRange:isSoft:actualCharacterRange:
• – invalidateLayoutForCharacterRange:actualCharacterRange:
• – invalidateDisplayForCharacterRange:
• – invalidateDisplayForGlyphRange:
• – layoutManagerDidInvalidateLayout:  delegate method
• – textContainerChangedGeometry:
• – textContainerChangedTextView:
• – textStorage:edited:range:changeInLength:invalidatedRange:

Enabling Background Layout

• – setBackgroundLayoutEnabled:
• – backgroundLayoutEnabled

Accessing Glyphs

• – insertGlyph:atGlyphIndex:characterIndex:
• – isValidGlyphIndex:
• – glyphAtIndex:
• – glyphAtIndex:isValidIndex:
• – replaceGlyphAtIndex:withGlyph:
• – getGlyphs:range:
• – getGlyphsInRange:glyphs:characterIndexes:glyphInscriptions:elasticBits:
• – getGlyphsInRange:glyphs:characterIndexes:glyphInscriptions:elasticBits:bidiLevels:
• – deleteGlyphsInRange:
• – numberOfGlyphs

Mapping Characters to Glyphs

• – setCharacterIndex:forGlyphAtIndex:
• – characterIndexForGlyphAtIndex:
• – glyphIndexForCharacterAtIndex:
• – characterRangeForGlyphRange:actualGlyphRange:
• – glyphRangeForCharacterRange:actualCharacterRange:

Setting Glyph Attributes

• – intAttribute:forGlyphAtIndex:
• – setAttachmentSize:forGlyphRange:
• – attachmentSizeForGlyphAtIndex:
• – setDefaultAttachmentScaling:
• – defaultAttachmentScaling
• – showAttachmentCell:inRect:characterIndex:

Handling Layout for Text Containers

• – setTextContainer:forGlyphRange:
• – glyphRangeForTextContainer:
• – textContainerForGlyphAtIndex:effectiveRange:
• – textContainerForGlyphAtIndex:effectiveRange:withoutAdditionalLayout:
• – usedRectForTextContainer:
• – layoutManager:didCompleteLayoutForTextContainer:atEnd:  delegate method

Handling Line Fragment Rectangles

• – setLineFragmentRect:forGlyphRange:usedRect:
• – lineFragmentRectForGlyphAtIndex:effectiveRange:
• – lineFragmentRectForGlyphAtIndex:effectiveRange:withoutAdditionalLayout:
• – lineFragmentUsedRectForGlyphAtIndex:effectiveRange:
• – lineFragmentUsedRectForGlyphAtIndex:effectiveRange:withoutAdditionalLayout:
• – setExtraLineFragmentRect:usedRect:textContainer:
• – extraLineFragmentRect
• – extraLineFragmentUsedRect
• – extraLineFragmentTextContainer
• – setDrawsOutsideLineFragment:forGlyphAtIndex:
• – drawsOutsideLineFragmentForGlyphAtIndex:

Laying Out Glyphs

• – setLocation:forStartOfGlyphRange:
• – setLocations:startingGlyphIndexes:count:forGlyphRange:
• – locationForGlyphAtIndex:
• – rangeOfNominallySpacedGlyphsContainingIndex:
• – getLineFragmentInsertionPointsForCharacterAtIndex:alternatePositions:inDisplayOrder:positions:characterIndexes:
• – rectArrayForCharacterRange:withinSelectedCharacterRange:inTextContainer:rectCount:
• – rectArrayForGlyphRange:withinSelectedGlyphRange:inTextContainer:rectCount:
• – boundingRectForGlyphRange:inTextContainer:
• – glyphRangeForBoundingRect:inTextContainer:
• – glyphRangeForBoundingRectWithoutAdditionalLayout:inTextContainer:
• – glyphIndexForPoint:inTextContainer:fractionOfDistanceThroughGlyph:
• – fractionOfDistanceThroughGlyphForPoint:inTextContainer:
• – glyphIndexForPoint:inTextContainer:

Handling Layout for Text Blocks

• – setLayoutRect:forTextBlock:glyphRange:
• – layoutRectForTextBlock:glyphRange:
• – setBoundsRect:forTextBlock:glyphRange:
• – boundsRectForTextBlock:glyphRange:
• – layoutRectForTextBlock:atIndex:effectiveRange:
• – boundsRectForTextBlock:atIndex:effectiveRange:

Displaying Special Glyphs

• – setNotShownAttribute:forGlyphAtIndex:
• – notShownAttributeForGlyphAtIndex:
• – setShowsInvisibleCharacters:
• – showsInvisibleCharacters
• – setShowsControlCharacters:
• – showsControlCharacters

Controlling Hyphenation

• – setHyphenationFactor:
• – hyphenationFactor

Finding Characters and Glyphs Not Laid Out

• – getFirstUnlaidCharacterIndex:glyphIndex:
• – firstUnlaidCharacterIndex
• – firstUnlaidGlyphIndex

Using Screen Fonts

• – setUsesScreenFonts:
• – usesScreenFonts
• – substituteFontForFont:

Handling Rulers

• – rulerAccessoryViewForTextView:paragraphStyle:ruler:enabled:
• – rulerMarkersForTextView:paragraphStyle:ruler:

Managing the Responder Chain

• – layoutManagerOwnsFirstResponderInWindow:
• – firstTextView
• – textViewForBeginningOfSelection

Drawing

• – drawBackgroundForGlyphRange:atPoint:
• – drawGlyphsForGlyphRange:atPoint:
• – drawUnderlineForGlyphRange:underlineType:baselineOffset:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:
• – underlineGlyphRange:underlineType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:
• – showPackedGlyphs:length:glyphRange:atPoint:font:color:printingAdjustment:
• – drawStrikethroughForGlyphRange:strikethroughType:baselineOffset:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:
• – strikethroughGlyphRange:strikethroughType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:

Accessing the Delegate

• – setDelegate:
• – delegate

Accessing the Typesetter

• – setTypesetter:
• – typesetter

Managing Typesetter Compatibility

• – setTypesetterBehavior:
• – typesetterBehavior
• – defaultLineHeightForFont:
• – defaultBaselineOffsetForFont:

Managing Temporary Attribute Support

• – addTemporaryAttributes:forCharacterRange:
• – addTemporaryAttribute:value:forCharacterRange:
• – setTemporaryAttributes:forCharacterRange:
• – removeTemporaryAttribute:forCharacterRange:
• – temporaryAttribute:atCharacterIndex:effectiveRange:
• – temporaryAttribute:atCharacterIndex:longestEffectiveRange:inRange:
• – temporaryAttributesAtCharacterIndex:effectiveRange:
• – temporaryAttributesAtCharacterIndex:longestEffectiveRange:inRange:
• – layoutManager:shouldUseTemporaryAttributes:forDrawingToScreen:atCharacterIndex:effectiveRange:  delegate method

Managing Noncontiguous Layout

• – setAllowsNonContiguousLayout:
• – allowsNonContiguousLayout
• – hasNonContiguousLayout
• – ensureGlyphsForCharacterRange:
• – ensureGlyphsForGlyphRange:
• – ensureLayoutForCharacterRange:
• – ensureLayoutForGlyphRange:
• – ensureLayoutForTextContainer:
• – ensureLayoutForBoundingRect:inTextContainer:

Accessing the Font Leading

• – usesFontLeading
• – setUsesFontLeading:

Instance Methods

addTemporaryAttribute:value:forCharacterRange:

Adds a temporary attribute with the given name and value to the characters in the specified range.

- (void)addTemporaryAttribute:(NSString *)attrName value:(id)value forCharacterRange:(NSRange)charRange

Parameters

attrName

The name of a temporary attribute.

value

The temporary attribute value associated with attrName.

charRange

The range of characters to which the specified attribute-value pair applies.

Discussion

Raises an NSInvalidArgumentException if attrName or value is nil.

Availability

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

See Also

• – addTemporaryAttributes:forCharacterRange:
• – setTemporaryAttributes:forCharacterRange:
• – removeTemporaryAttribute:forCharacterRange:
• – temporaryAttributesAtCharacterIndex:effectiveRange:

Declared In

NSLayoutManager.h

addTemporaryAttributes:forCharacterRange:

Appends one or more temporary attributes to the attributes dictionary of the specified character range.

- (void)addTemporaryAttributes:(NSDictionary *)attrs forCharacterRange:(NSRange)charRange

Parameters

attrs

Attributes dictionary containing the temporary attributes to add.

charRange

The range of characters to which the specified attributes apply.

Discussion

Temporary attributes are used only for onscreen drawing and are not persistent in any way. NSTextView uses them to color misspelled words when continuous spell checking is enabled. Currently the only temporary attributes recognized are those that do not affect layout (colors, underlines, and so on).

Availability

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

See Also

• – setTemporaryAttributes:forCharacterRange:
• – removeTemporaryAttribute:forCharacterRange:
• – temporaryAttributesAtCharacterIndex:effectiveRange:

Declared In

NSLayoutManager.h

addTextContainer:

Appends the given text container to the series of text containers where the receiver arranges text.

- (void)addTextContainer:(NSTextContainer *)aTextContainer

Parameters

aTextContainer

The text container to append.

Discussion

Invalidates glyphs and layout as needed, but doesn’t perform glyph generation or layout.

Availability

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

See Also

• – insertTextContainer:atIndex:
• – removeTextContainerAtIndex:
• – textContainers
• – invalidateGlyphsForCharacterRange:changeInLength:actualCharacterRange:
• – invalidateLayoutForCharacterRange:isSoft:actualCharacterRange:

Declared In

NSLayoutManager.h

allowsNonContiguousLayout

Indicates whether noncontiguous layout is enabled or disabled.

- (BOOL)allowsNonContiguousLayout

Return Value

YES if noncontiguous layout is enabled; otherwise, NO.

Discussion

For more information about noncontiguous layout, see “Noncontiguous Layout.”

Availability

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

See Also

• – setAllowsNonContiguousLayout:
• – hasNonContiguousLayout

Declared In

NSLayoutManager.h

attachmentSizeForGlyphAtIndex:

For a glyph corresponding to an attachment, returns the size for the attachment cell to occupy.

- (NSSize)attachmentSizeForGlyphAtIndex:(NSUInteger)glyphIndex

Parameters

glyphIndex

The index of the attachment glyph.

Return Value

The size for the attachment cell to occupy. Returns {-1.0, -1.0} if there is no attachment laid for the specified glyph.

Availability

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

See Also

• – setAttachmentSize:forGlyphRange:
• – defaultAttachmentScaling

Declared In

NSLayoutManager.h

backgroundLayoutEnabled

Indicates whether the receiver generates glyphs and lays out text when the application’s run loop is idle.

- (BOOL)backgroundLayoutEnabled

Return Value

YES if the receiver generates glyphs and lays out text when the application’s run loop is idle, NO if it performs glyph generation and layout only when necessary.

Availability

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

See Also

• – setBackgroundLayoutEnabled:

Declared In

NSLayoutManager.h

boundingRectForGlyphRange:inTextContainer:

Returns a single bounding rectangle (in container coordinates) enclosing all glyphs and other marks drawn in the given text container for the given glyph range, including glyphs that draw outside their line fragment rectangles and text attributes such as underlining.

- (NSRect)boundingRectForGlyphRange:(NSRange)glyphRange inTextContainer:(NSTextContainer *)container

Parameters

glyphRange

The range of glyphs for which to return the bounding rectangle.

container

The text container in which the glyphs are laid out.

Return Value

The bounding rectangle enclosing the given range of glyphs.

Discussion

The range is intersected with the container's range before computing the bounding rectangle. This method can be used to translate glyph ranges into display rectangles for invalidation and redrawing when a range of glyphs changes. Bounding rectangles are always in container coordinates.

Performs glyph generation and layout if needed.

Availability

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

See Also

• – glyphRangeForBoundingRect:inTextContainer:
• – glyphRangeForTextContainer:
• – drawsOutsideLineFragmentForGlyphAtIndex:

Declared In

NSLayoutManager.h

boundsRectForTextBlock:atIndex:effectiveRange:

Returns the bounding rectangle within which the given text block containing the glyph at the given index is to be laid out.

- (NSRect)boundsRectForTextBlock:(NSTextBlock *)block atIndex:(NSUInteger)glyphIndex effectiveRange:(NSRangePointer)effectiveGlyphRange

Parameters

block

The text block whose bounding rectangle is returned.

glyphIndex

Index of the glyph.

effectiveGlyphRange

If not NULL, on output, the range for all glyphs in the text block.

Return Value

The bounding rectangle of the text block, or NSZeroRect if no rectangle has been set for the specified block since the last invalidation.

Discussion

This method causes glyph generation but not layout. Block layout rectangles and bounds rectangles are always in container coordinates.

Availability

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

See Also

• – setBoundsRect:forTextBlock:glyphRange:

Declared In

NSLayoutManager.h

boundsRectForTextBlock:glyphRange:

Returns the bounding rectangle enclosing the given text block containing the given glyph range.

- (NSRect)boundsRectForTextBlock:(NSTextBlock *)block glyphRange:(NSRange)glyphRange

Parameters

block

The text block whose bounds rectangle is returned.

glyphRange

The range of glyphs in the text block.

Return Value

The bounding rectangle, or NSZeroRect if no rectangle has been set for the specified block since the last invalidation

Discussion

This method causes glyph generation but not layout. Block layout rectangles and bounds rectangles are always in container coordinates.

Availability

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

See Also

• – setBoundsRect:forTextBlock:glyphRange:

Declared In

NSLayoutManager.h

characterIndexForGlyphAtIndex:

Returns the index in the text storage for the first character associated with the given glyph.

- (NSUInteger)characterIndexForGlyphAtIndex:(NSUInteger)glyphIndex

Parameters

glyphIndex

The index of the glyph for which to return the associated character.

Return Value

The index of the first character associated with the glyph at the specified index.

Discussion

If noncontiguous layout is not enabled, this method causes generation of all glyphs up to and including glyphIndex. This method accepts an index beyond the last glyph, returning an index extrapolated from the last actual glyph index.

In many cases it’s better to use the range-mapping methods, characterRangeForGlyphRange:actualGlyphRange: and glyphRangeForCharacterRange:actualCharacterRange:, which provide more comprehensive information.

Availability

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

See Also

• – glyphIndexForCharacterAtIndex:

Declared In

NSLayoutManager.h

characterRangeForGlyphRange:actualGlyphRange:

Returns the range of characters that generated the glyphs in the given glyph range.

- (NSRange)characterRangeForGlyphRange:(NSRange)glyphRange actualGlyphRange:(NSRangePointer)actualGlyphRange

Parameters

glyphRange

The glyph range for which to return the character range.

actualGlyphRange

If not NULL, on output, points to the full range of glyphs generated by the character range returned. This range may be identical or slightly larger than the requested glyph range. For example, if the text storage contains the character “Ö” and the glyph cache contains the two atomic glyphs “O” and “¨”, and if glyphRange encloses only the first or second glyph, then actualGlyphRange is set to enclose both gly