Class

NSLayoutManager

An object that coordinates the layout and display of characters held in an NSTextStorage object.

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

Initializing the Layout Manager

- init

Initializes the receiver, a newly created NSLayoutManager object.

Accessing the Text Storage

textStorage

The receiver’s NSTextStorage object.

- replaceTextStorage:

Replaces the NSTextStorage object for the group of text-system objects containing the receiver with the given text storage object.

Accessing the Delegate

delegate

The receiver’s delegate.

Managing the Text Containers

textContainers

The receiver’s text containers.

- addTextContainer:

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

- insertTextContainer:atIndex:

Inserts the given text container into the series of text containers at the given index.

- removeTextContainerAtIndex:

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

- setTextContainer:forGlyphRange:

Sets text container where the glyphs in the given range are laid out.

- textContainerChangedGeometry:

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

- textContainerChangedTextView:

Updates information needed to manage NSTextView objects in the given text container.

- textContainerForGlyphAtIndex:effectiveRange:

Returns the container in which the given glyph is laid out and (optionally) by reference the whole range of glyphs that are in that container.

- textContainerForGlyphAtIndex:effectiveRange:withoutAdditionalLayout:

Returns the container in which the given glyph is laid out and (optionally) by reference the whole range of glyphs that are in that container.

- usedRectForTextContainer:

Returns the bounding rectangle for the glyphs laid out in the given text container.

Configuring the Global Layout Manager Options

allowsNonContiguousLayout

A Boolean that enables or disables noncontiguous layout.

hasNonContiguousLayout

Indicates whether the layout manager currently has any areas of noncontiguous layout.

hyphenationFactor

The threshold controlling when hyphenation is done.

Deprecated
showsInvisibleCharacters

A Boolean that specifies whether to substitute visible glyphs for whitespace and other typically invisible characters in layout.

showsControlCharacters

A Boolean that specifies whether to substitute visible glyphs for control characters in layout.

usesFontLeading

Indicates whether the receiver uses the leading provided in the font.

backgroundLayoutEnabled

A Boolean that specifies whether the receiver generates glyphs and lays them out when the application’s run loop is idle.

Invalidating Glyphs and Layout

- invalidateDisplayForCharacterRange:

Invalidates display for the given character range.

- invalidateDisplayForGlyphRange:

Marks the glyphs in the given glyph range as needing display, as well as the appropriate regions of the NSTextView objects that display those glyphs (using the NSView method setNeedsDisplayInRect:).

- invalidateGlyphsForCharacterRange:changeInLength:actualCharacterRange:

Invalidates the cached glyphs for the characters in the given character range, adjusts the character indices of all the subsequent glyphs by the change in length, and invalidates the new character range.

- invalidateLayoutForCharacterRange:actualCharacterRange:

Invalidates the layout information for the glyphs mapped to the given range of characters.

- processEditingForTextStorage:edited:range:changeInLength:invalidatedRange:

Sent from the NSTextStorage method processEditing to notify the layout manager of 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 this 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, otherwise NO.

numberOfGlyphs

The number of glyphs in the receiver.

- propertyForGlyphAtIndex:

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

Setting Layout Information

- setAttachmentSize:forGlyphRange:

Sets the size at which the given glyph (assumed to be an attachment) is asked to draw in the given glyph range.

- setDrawsOutsideLineFragment:forGlyphAtIndex:

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

- setExtraLineFragmentRect:usedRect:textContainer:

Sets the bounds and container for the extra line fragment.

- setLineFragmentRect:forGlyphRange:usedRect:

Associates the given line fragment bounds with the given range of glyphs.

- setLocation:forStartOfGlyphRange:

Sets the location for the first glyph of the given range.

- setNotShownAttribute:forGlyphAtIndex:

Sets the glyph at the given index to be one that isn’t shown.

Getting Layout Information

- attachmentSizeForGlyphAtIndex:

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

- drawsOutsideLineFragmentForGlyphAtIndex:

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

extraLineFragmentRect

The rectangle defining the extra line fragment for the insertion point at the end of a text (either in an empty text or after a final paragraph separator).

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 given glyph is laid out and (optionally), by reference, the whole range of glyphs that are 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 in which the given glyph is laid and (optionally) by reference the whole range of glyphs that are in that fragment.

- lineFragmentUsedRectForGlyphAtIndex:effectiveRange:withoutAdditionalLayout:

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

- locationForGlyphAtIndex:

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

- notShownAttributeForGlyphAtIndex:

Indicates whether the glyph at the given index is one that isn’t shown.

- truncatedGlyphRangeInLineFragmentForGlyphAtIndex:

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

Performing Advanced Layout Queries

- 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.

- 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 generated the glyphs in the given glyph range.

- enumerateEnclosingRectsForGlyphRange:withinSelectedGlyphRange:inTextContainer:usingBlock:

Enumerates enclosing rectangles for the given glyph range in the given text container.

- enumerateLineFragmentsForGlyphRange:usingBlock:

Enumerates line fragments intersecting with the given glyph range.

- fractionOfDistanceThroughGlyphForPoint:inTextContainer:

This method is a primitive for glyphIndexForPoint:inTextContainer:fractionOfDistanceThroughGlyph:. You should always call the main method, not the primitives.

- glyphIndexForPoint:inTextContainer:

This method is a primitive for glyphIndexForPoint:inTextContainer:fractionOfDistanceThroughGlyph:. You should always call the main method, not the primitives.

- glyphIndexForPoint:inTextContainer:fractionOfDistanceThroughGlyph:

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

- glyphRangeForBoundingRect:inTextContainer:

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

- glyphRangeForBoundingRectWithoutAdditionalLayout:inTextContainer:

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

- glyphRangeForTextContainer:

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

- glyphRangeForCharacterRange:actualCharacterRange:

Returns the range of glyphs that are generated from the characters in the given character range.

- rangeOfNominallySpacedGlyphsContainingIndex:

Returns the range for the glyphs around the given glyph that can be displayed using only their advancements from the font, without pairwise kerning or other adjustments to spacing.

Drawing

- drawBackgroundForGlyphRange:atPoint:

Draws background marks for the given glyph range, which must lie completely within a single text container.

- drawGlyphsForGlyphRange:atPoint:

Draws the glyphs in the given glyph range, which must lie completely within a single text container.

- fillBackgroundRectArray:count:forCharacterRange:color:

Fills background rectangles with a color.

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

Renders the glyphs at the specified positions and attributes into the graphicsContext.

Deprecated
- strikethroughGlyphRange:strikethroughType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:

Calculates and draws strikethrough for the glyphs in the given range.

- underlineGlyphRange:underlineType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:

Calculates subranges to be underlined for the glyphs in a given range and draws the underlining as appropriate.

Handling Layout for Text Blocks

- setLayoutRect:forTextBlock:glyphRange:

Sets the layout rectangle enclosing the given text block containing the given glyph range.

- layoutRectForTextBlock:glyphRange:

Returns the layout rectangle within which the given text block containing the given glyph range is to be laid out.

- setBoundsRect:forTextBlock:glyphRange:

Sets the bounding rectangle enclosing a given text block containing the given glyph range.

- boundsRectForTextBlock:glyphRange:

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

- layoutRectForTextBlock:atIndex:effectiveRange:

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

- 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.

Managing Attachments

defaultAttachmentScaling

The default scaling behavior to the given scaling if 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 given window is a text view associated with the receiver.

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.

- defaultLineHeightForFont:

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

- defaultBaselineOffsetForFont:

Returns the default baseline offset specified by the layout manager's typesetter behavior for the given 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 with the given name and value 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 with a given name of the character at a given index, and by reference the range over which the attribute applies.

- temporaryAttribute:atCharacterIndex:longestEffectiveRange:inRange:

Returns the value for the temporary attribute with a given name of the character at a given index, and by reference the maximum range over which the attribute applies.

- temporaryAttributesAtCharacterIndex:effectiveRange:

Returns the dictionary of temporary attributes for the character range specified in effectiveCharRange at character index charIndex.

- temporaryAttributesAtCharacterIndex:longestEffectiveRange:inRange:

Returns the temporary attributes for the character at a given index, and by reference the maximum range over which the attributes apply.

Deprecated

attributedString

The text storage object from which the NSGlyphGenerator object procures characters for glyph generation.

- invalidateGlyphsOnLayoutInvalidationForGlyphRange:

Specifies explicitly when portions of the glyph stream depend on layout.

Deprecated
- invalidateLayoutForCharacterRange:isSoft:actualCharacterRange:

Invalidates the layout information for the glyphs mapped to the given range of characters.

Deprecated
- textStorage:edited:range:changeInLength:invalidatedRange:

Invalidates glyph and layout information for a portion of the text in the given text storage object.

Deprecated
- insertGlyph:atGlyphIndex:characterIndex:

Inserts a single glyph into the glyph stream at the given index and maps it to the character at the given character index.

Deprecated
- insertGlyphs:length:forStartingGlyphAtIndex:characterIndex:

Inserts the given glyphs into the glyph cache at the given index and maps them to characters beginning at the given character index.

Deprecated
- glyphAtIndex:

Returns the glyph at glyphIndex.

Deprecated
- glyphAtIndex:isValidIndex:

If the given index is valid, returns the glyph at that location and optionally returns a flag indicating whether the requested index is in range.

Deprecated
- replaceGlyphAtIndex:withGlyph:

Replaces the glyph at the given index with a new glyph.

Deprecated
- getGlyphs:range:

Fills the passed-in buffer with a sequence of glyphs

Deprecated
- getGlyphsInRange:glyphs:characterIndexes:glyphInscriptions:elasticBits:

Returns the glyphs and information needed to perform layout for the given glyph range.

Deprecated
- getGlyphsInRange:glyphs:characterIndexes:glyphInscriptions:elasticBits:bidiLevels:

Returns the glyphs and information needed to perform layout for the given glyph range.

Deprecated
- deleteGlyphsInRange:

Deletes the glyphs in the given range from the receiver’s glyph store.

Deprecated
- setCharacterIndex:forGlyphAtIndex:

Sets the index of the character corresponding to the glyph at the given glyph index.

Deprecated
- intAttribute:forGlyphAtIndex:

Returns the value of the attribute identified by the given attribute tag for the glyph at the given index.

Deprecated
- setIntAttribute:value:forGlyphAtIndex:

Sets a custom attribute value for a given glyph.

Deprecated
- setLocations:startingGlyphIndexes:count:forGlyphRange:

Sets locations for many glyph ranges at once.

Deprecated
- rectArrayForCharacterRange:withinSelectedCharacterRange:inTextContainer:rectCount:

Returns an array of rectangles and, by reference, the number of such rectangles, that define the region in the given container enclosing the given character range.

Deprecated
- rectArrayForGlyphRange:withinSelectedGlyphRange:inTextContainer:rectCount:

Returns an array of rectangles and, by reference, the number of such rectangles, that define the region in the given container enclosing the given glyph range.

Deprecated
- layoutOptions

The layout manager’s current layout options.

usesScreenFonts

A Boolean that controls using screen fonts to calculate layout and display text.

Deprecated
- substituteFontForFont:

Returns a screen font suitable for use in place of the given font, if one is available.

Deprecated

Constants

Glyph Attributes

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

Deprecated
NSTextLayoutOrientation

Describes the text layout orientation.

NSGlyphProperty

Glyph properties.

NSControlCharacterAction

Actions that control characters can cause.

NSGlyphInscription

Constants that specify how a glyph is laid out relative to the previous glyph.

Deprecated
NSTypesetterBehavior

These constants define the behavior of NSLayoutManager and NSTypesetter when laying out lines. They are used by typesetterBehavior to control the compatibility level of the typesetter.

Relationships

Inherits From

Conforms To

See Also

Layout

NSLayoutManagerDelegate

A set of optional methods implemented by delegates of NSLayoutManager objects.

NSTextLayoutOrientationProvider

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