Class

NSLayoutManager

An object that coordinates the layout and display of text characters.

Declaration

@interface NSLayoutManager : NSObject

Overview

NSLayoutManager 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, a layout manager object coordinates its text view 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. In macOS, 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 in more than one block, operation, or 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 you want to use a layout manager 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. The most effective way to ensure that no text view is displayed, without knowing deep implementation, is just not to connect a text view to the layout manager.

Noncontiguous Layout

Noncontiguous layout is an optional layout manager behavior. 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.

Enable noncontiguous layout using the allowsNonContiguousLayout property. In addition, see the other methods in Causing Glyph Generation and 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.

Topics

Creating a Layout Manager

- init

Initializes a newly created layout manager object.

Managing the Layout Process

delegate

The receiver’s delegate.

NSLayoutManagerDelegate

A set of optional methods implemented by delegates of layout manager objects.

Accessing the Text Storage

textStorage

The text storage object containing the content to be laid out.

- replaceTextStorage:

Replaces the layout manager's current text storage object with the specified object.

Configuring the Global Layout Manager Options

allowsNonContiguousLayout

A Boolean value indicating whether the layout manager allows noncontiguous layout.

hasNonContiguousLayout

A Boolean value indicating whether the layout manager currently has any areas of noncontiguous layout.

showsInvisibleCharacters

A Boolean value that indicates whether to substitute visible glyphs for white space and other typically invisible characters.

showsControlCharacters

A Boolean value indicating whether the layout manager substitutes visible glyphs for control characters in layout.

usesFontLeading

A Boolean value indicating whether the layout manager uses the leading provided in the font.

backgroundLayoutEnabled

A Boolean value indicating whether the layout manager generates glyphs and lays them out when the app's run loop is idle.

limitsLayoutForSuspiciousContents

A Boolean value indicating whether the layout manager aborts layout for unusually long or suspicious input.

usesDefaultHyphenation

A Boolean value indicating whether the layout manager uses the default hyphenation rules to wrap lines.

Managing the Text Containers

textContainers

The current text containers of the layout manager.

- addTextContainer:

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

- insertTextContainer:atIndex:

Inserts a text container at the specified index in the list of text containers.

- removeTextContainerAtIndex:

Removes the text container at the specified index and invalidates the layout as needed.

- setTextContainer:forGlyphRange:

Associates a text container with the specified range of glyphs.

- textContainerChangedGeometry:

Invalidates the layout information, and possibly glyphs, for the specified text container and all subsequent text container objects.

- textContainerChangedTextView:

Updates the information needed to manage text view objects associated with the specified text container.

- textContainerForGlyphAtIndex:effectiveRange:

Returns the text container that manages the layout for the specified glyph, causing layout to happen as needed.

- textContainerForGlyphAtIndex:effectiveRange:withoutAdditionalLayout:

Returns the text container that manages the layout for the specified glyph.

- usedRectForTextContainer:

Returns the bounding rectangle for the glyphs in the specified text container.

Invalidating Glyphs and Layout

- invalidateDisplayForCharacterRange:

Invalidates display for the specified character range.

- invalidateDisplayForGlyphRange:

Invalidates a range of glyphs, requiring new layout information, and updates the appropriate regions of any text views that display those glyphs.

- invalidateGlyphsForCharacterRange:changeInLength:actualCharacterRange:

Invalidates and adjusts the glyphs in the specified character range.

- invalidateLayoutForCharacterRange:actualCharacterRange:

Invalidates the layout information for the glyphs mapped to the specified character range.

- processEditingForTextStorage:edited:range:changeInLength:invalidatedRange:

Notifies the layout manager that the contents of its text storage object changed due to an edit action.

Causing Glyph Generation and Layout

- ensureGlyphsForCharacterRange:

Forces the receiver to generate glyphs for the specified character range, if it has not already done so.

- ensureGlyphsForGlyphRange:

Forces the receiver to generate glyphs for the specified glyph range, if it has not already done so.

- ensureLayoutForBoundingRect:inTextContainer:

Forces the receiver to perform layout for the specified area in the specified text container, if it has not already done so.

- ensureLayoutForCharacterRange:

Forces the receiver to perform layout for the specified character range, if it has not already done so.

- ensureLayoutForGlyphRange:

Forces the receiver to perform layout for the specified glyph range, if it has not already done so.

- ensureLayoutForTextContainer:

Forces the receiver to perform layout for the specified text container, if it has not already done so.

glyphGenerator

The glyph generator used by the layout manager.

Accessing Glyphs

- getGlyphsInRange:glyphs:properties:characterIndexes:bidiLevels:

Fills a passed-in buffer with a sequence of glyphs.

- CGGlyphAtIndex:

Returns the glyph at the specified index.

- CGGlyphAtIndex:isValidIndex:

Returns the glyph at the specified index and information about whether the glyph index is valid.

- setGlyphs:properties:characterIndexes:font:forGlyphRange:

Stores the initial glyphs and glyph properties for a character range.

- characterIndexForGlyphAtIndex:

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

- glyphIndexForCharacterAtIndex:

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

- isValidGlyphIndex:

Indicates whether the specified index refers to a valid glyph.

numberOfGlyphs

The number of glyphs in the receiver.

- propertyForGlyphAtIndex:

Returns the glyph property associated with the glyph at the specified index.

NSGlyphProperty

Glyph properties.

Setting Layout Information

- setAttachmentSize:forGlyphRange:

Sets the size to use when drawing a glyph that represents an attachment.

- setDrawsOutsideLineFragment:forGlyphAtIndex:

Specifies whether the given glyph exceeds the bounds of the line fragment on which it’s laid out.

- setExtraLineFragmentRect:usedRect:textContainer:

Sets the bounds and container for the extra line fragment.

- setLineFragmentRect:forGlyphRange:usedRect:

Associates the line fragment bounds for the specified range of glyphs.

- setLocation:forStartOfGlyphRange:

Sets the location for the first glyph in the specified range.

- setNotShownAttribute:forGlyphAtIndex:

Sets the visibility of the glyph at the specified index.

Getting Layout Information

- attachmentSizeForGlyphAtIndex:

Returns the size of the attachment glyph at the specified index.

- drawsOutsideLineFragmentForGlyphAtIndex:

Indicates whether the glyph draws outside of its line fragment rectangle.

extraLineFragmentRect

The rectangle for the extra line fragment at the end of a document.

extraLineFragmentTextContainer

The text container that contains the extra line fragment rectangle.

extraLineFragmentUsedRect

The rectangle enclosing the insertion point drawn in the extra line fragment rectangle.

- firstUnlaidCharacterIndex

The index for the first character in the layout manager that has not been laid out.

- firstUnlaidGlyphIndex

The index for the first glyph in the layout manager that has not been laid out.

- getFirstUnlaidCharacterIndex:glyphIndex:

Returns the indexes for the first character and glyph that have invalid layout information.

- lineFragmentRectForGlyphAtIndex:effectiveRange:

Returns the rectangle for the line fragment in which the glyph is laid out and (optionally), by reference, the whole range of glyphs in that fragment.

- lineFragmentRectForGlyphAtIndex:effectiveRange:withoutAdditionalLayout:

Returns the line fragment rectangle containing the glyph at the given glyph index.

- lineFragmentUsedRectForGlyphAtIndex:effectiveRange:

Returns the usage rectangle for the line fragment and (optionally) returns the whole range of glyphs in that fragment.

- lineFragmentUsedRectForGlyphAtIndex:effectiveRange:withoutAdditionalLayout:

Returns the usage rectangle for the line fragment and (optionally) returns the whole range of glyphs that are in that fragment.

- locationForGlyphAtIndex:

Returns the location for the specified glyph within its line fragment.

- notShownAttributeForGlyphAtIndex:

Indicates whether the glyph at the specified index has a visible representation.

- truncatedGlyphRangeInLineFragmentForGlyphAtIndex:

Returns the range of truncated glyphs for a line fragment containing the specified index.

Performing Advanced Layout Queries

- boundingRectForGlyphRange:inTextContainer:

Returns the bounding rectangle for the specified glyphs in a container.

- characterIndexForPoint:inTextContainer:fractionOfDistanceBetweenInsertionPoints:

Returns the index of the character falling under the given point, expressed in the given container's coordinate system.

- characterRangeForGlyphRange:actualGlyphRange:

Returns the range of characters that correspond to the glyphs in the specified glyph range.

- enumerateEnclosingRectsForGlyphRange:withinSelectedGlyphRange:inTextContainer:usingBlock:

Enumerates enclosing rectangles for the specified glyph range in a text container.

- enumerateLineFragmentsForGlyphRange:usingBlock:

Enumerates line fragments intersecting with the specified glyph range.

- fractionOfDistanceThroughGlyphForPoint:inTextContainer:

Returns the fraction of the distance between the glyph at the specified point and the next glyph.

- glyphIndexForPoint:inTextContainer:

Returns the index of the glyph at the specified location in a text container.

- glyphIndexForPoint:inTextContainer:fractionOfDistanceThroughGlyph:

Returns the index of the glyph at the specified point, expressed in the container's coordinate system.

- glyphRangeForBoundingRect:inTextContainer:

Returns the smallest contiguous range for glyphs that are laid out wholly or partially within the specified rectangle of the text container.

- glyphRangeForBoundingRectWithoutAdditionalLayout:inTextContainer:

Returns the smallest contiguous range for glyphs that are laid out wholly or partially within the specified rectangle of the text container.

- glyphRangeForTextContainer:

Returns the range of glyphs laid out within the specified text container.

- glyphRangeForCharacterRange:actualCharacterRange:

Returns the range of glyphs that are generated from the specified range of characters.

- rangeOfNominallySpacedGlyphsContainingIndex:

Returns the range of displayable glyphs that surround the glyph at the specified index.

Drawing

- drawBackgroundForGlyphRange:atPoint:

Draws background marks for the specified glyphs, which must lie completely within a single text container.

- drawGlyphsForGlyphRange:atPoint:

Draws the specified glyphs, which must lie completely within a single text container.

- fillBackgroundRectArray:count:forCharacterRange:color:

Fills background rectangles with a color.

- showCGGlyphs:positions:count:font:textMatrix:attributes:inContext:

Renders the glyphs at the specified positions, using the specified attributes.

- underlineGlyphRange:underlineType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:

Calculates subranges to be underlined for the specified glyphs and draws the underlining as appropriate.

Glyph Attributes

Attributes that are used only inside the glyph generation machinery, but must also be shared between components.

Deprecated

Handling Layout for Text Blocks

- setLayoutRect:forTextBlock:glyphRange:

Sets the layout rectangle enclosing the specified text block and glyph range.

- layoutRectForTextBlock:glyphRange:

Returns the rectangle in which to lay out the specified text block and glyph range.

- setBoundsRect:forTextBlock:glyphRange:

Sets the bounding rectangle enclosing the specified text block and glyph range.

- boundsRectForTextBlock:glyphRange:

Returns the bounding rectangle enclosing the specified text block and glyph range.

- layoutRectForTextBlock:atIndex:effectiveRange:

Returns the rectangle in which to lay out the specified text block and glyph.

- boundsRectForTextBlock:atIndex:effectiveRange:

Returns the bounding rectangle for the specified text block and glyph.

Managing Attachments

defaultAttachmentScaling

The default amount of scaling to apply when an attachment image is too large to fit in a text container.

Handling Rulers

- rulerAccessoryViewForTextView:paragraphStyle:ruler:enabled:

Returns the accessory view that the text system uses for its ruler.

- rulerMarkersForTextView:paragraphStyle:ruler:

Returns an array of text ruler objects for the current selection.

Managing the Responder Chain

- layoutManagerOwnsFirstResponderInWindow:

Indicates whether the first responder in the specified window is a text view associated with the layout manager.

firstTextView

The first text view in the receiver’s series of text views.

textViewForBeginningOfSelection

The text view containing the first glyph in the selection.

Managing the Typesetter

typesetter

The current typesetter.

typesetterBehavior

The default typesetter behavior.

NSTypesetterBehavior

Constants that determine the layout manager's behavior during layout.

- defaultLineHeightForFont:

Returns the default line height for a line of text drawn using a given font.

- defaultBaselineOffsetForFont:

Returns the default baseline offset that the layout manager's typesetter uses for the specified font.

Managing Temporary Attribute Support

- addTemporaryAttributes:forCharacterRange:

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

- addTemporaryAttribute:value:forCharacterRange:

Adds a temporary attribute to the characters in the specified range.

- setTemporaryAttributes:forCharacterRange:

Sets one or more temporary attributes for the specified character range.

- removeTemporaryAttribute:forCharacterRange:

Removes a temporary attribute from the list of attributes for the specified character range.

- temporaryAttribute:atCharacterIndex:effectiveRange:

Returns the value for the temporary attribute of a character, and the range to which the attribute applies.

- temporaryAttribute:atCharacterIndex:longestEffectiveRange:inRange:

Returns the value for the temporary attribute of a character, and the maximum range to which the attribute applies.

- temporaryAttributesAtCharacterIndex:effectiveRange:

Returns the dictionary of temporary attributes for the specified character range.

- temporaryAttributesAtCharacterIndex:longestEffectiveRange:inRange:

Returns the temporary attributes for a character, and the maximum range to which the attributes apply.

Deprecated

Deprecated Symbols

Review unsupported symbols and their replacements.

Relationships

Inherits From

Conforms To

See Also

Layout

NSLayoutManagerDelegate

A set of optional methods implemented by delegates of layout manager objects.

NSTextLayoutOrientationProvider

A set of methods that define the orientation of text for an object.