Class

NSLayoutManager

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

Declaration

class 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

var delegate: NSLayoutManagerDelegate?

The receiver’s delegate.

protocol NSLayoutManagerDelegate

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

Accessing the Text Storage

var textStorage: NSTextStorage?

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

func replaceTextStorage(NSTextStorage)

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

Configuring the Global Layout Manager Options

var allowsNonContiguousLayout: Bool

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

var hasNonContiguousLayout: Bool

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

var showsInvisibleCharacters: Bool

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

var showsControlCharacters: Bool

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

var usesFontLeading: Bool

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

var backgroundLayoutEnabled: Bool

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

var limitsLayoutForSuspiciousContents: Bool

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

var usesDefaultHyphenation: Bool

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

Managing the Text Containers

var textContainers: [NSTextContainer]

The current text containers of the layout manager.

func addTextContainer(NSTextContainer)

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

func insertTextContainer(NSTextContainer, at: Int)

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

func removeTextContainer(at: Int)

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

func setTextContainer(NSTextContainer, forGlyphRange: NSRange)

Associates a text container with the specified range of glyphs.

func textContainerChangedGeometry(NSTextContainer)

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

func textContainerChangedTextView(NSTextContainer)

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

func textContainer(forGlyphAt: Int, effectiveRange: NSRangePointer?) -> NSTextContainer?

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

func usedRect(for: NSTextContainer) -> CGRect

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

Invalidating Glyphs and Layout

func invalidateDisplay(forCharacterRange: NSRange)

Invalidates display for the specified character range.

func invalidateDisplay(forGlyphRange: NSRange)

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

func invalidateLayout(forCharacterRange: NSRange, actualCharacterRange: NSRangePointer?)

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

func processEditing(for: NSTextStorage, edited: NSTextStorage.EditActions, range: NSRange, changeInLength: Int, invalidatedRange: NSRange)

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

Causing Glyph Generation and Layout

func ensureGlyphs(forCharacterRange: NSRange)

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

func ensureGlyphs(forGlyphRange: NSRange)

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

func ensureLayout(forBoundingRect: CGRect, in: NSTextContainer)

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

func ensureLayout(forCharacterRange: NSRange)

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

func ensureLayout(forGlyphRange: NSRange)

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

func ensureLayout(for: NSTextContainer)

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

var glyphGenerator: NSGlyphGenerator

The glyph generator used by the layout manager.

Accessing Glyphs

func cgGlyph(at: Int) -> CGGlyph

Returns the glyph at the specified index.

func cgGlyph(at: Int, isValidIndex: UnsafeMutablePointer<ObjCBool>?) -> CGGlyph

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

func characterIndexForGlyph(at: Int) -> Int

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

func glyphIndexForCharacter(at: Int) -> Int

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

func isValidGlyphIndex(Int) -> Bool

Indicates whether the specified index refers to a valid glyph.

var numberOfGlyphs: Int

The number of glyphs in the receiver.

func propertyForGlyph(at: Int) -> NSLayoutManager.GlyphProperty

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

Setting Layout Information

func setAttachmentSize(CGSize, forGlyphRange: NSRange)

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

func setDrawsOutsideLineFragment(Bool, forGlyphAt: Int)

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

func setExtraLineFragmentRect(CGRect, usedRect: CGRect, textContainer: NSTextContainer)

Sets the bounds and container for the extra line fragment.

func setLineFragmentRect(CGRect, forGlyphRange: NSRange, usedRect: CGRect)

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

func setLocation(CGPoint, forStartOfGlyphRange: NSRange)

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

func setNotShownAttribute(Bool, forGlyphAt: Int)

Sets the visibility of the glyph at the specified index.

Getting Layout Information

func attachmentSize(forGlyphAt: Int) -> CGSize

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

func drawsOutsideLineFragment(forGlyphAt: Int) -> Bool

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

var extraLineFragmentRect: CGRect

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

var extraLineFragmentTextContainer: NSTextContainer?

The text container that contains the extra line fragment rectangle.

var extraLineFragmentUsedRect: CGRect

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

func firstUnlaidCharacterIndex() -> Int

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

func firstUnlaidGlyphIndex() -> Int

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

func getFirstUnlaidCharacterIndex(UnsafeMutablePointer<Int>?, glyphIndex: UnsafeMutablePointer<Int>?)

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

func lineFragmentRect(forGlyphAt: Int, effectiveRange: NSRangePointer?) -> CGRect

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.

func lineFragmentRect(forGlyphAt: Int, effectiveRange: NSRangePointer?, withoutAdditionalLayout: Bool) -> CGRect

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

func lineFragmentUsedRect(forGlyphAt: Int, effectiveRange: NSRangePointer?) -> CGRect

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

func lineFragmentUsedRect(forGlyphAt: Int, effectiveRange: NSRangePointer?, withoutAdditionalLayout: Bool) -> CGRect

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

func location(forGlyphAt: Int) -> CGPoint

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

func notShownAttribute(forGlyphAt: Int) -> Bool

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

func truncatedGlyphRange(inLineFragmentForGlyphAt: Int) -> NSRange

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

Performing Advanced Layout Queries

func boundingRect(forGlyphRange: NSRange, in: NSTextContainer) -> CGRect

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

func characterIndex(for: CGPoint, in: NSTextContainer, fractionOfDistanceBetweenInsertionPoints: UnsafeMutablePointer<CGFloat>?) -> Int

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

func characterRange(forGlyphRange: NSRange, actualGlyphRange: NSRangePointer?) -> NSRange

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

func fractionOfDistanceThroughGlyph(for: CGPoint, in: NSTextContainer) -> CGFloat

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

func glyphIndex(for: CGPoint, in: NSTextContainer) -> Int

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

func glyphIndex(for: CGPoint, in: NSTextContainer, fractionOfDistanceThroughGlyph: UnsafeMutablePointer<CGFloat>?) -> Int

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

func glyphRange(forBoundingRect: CGRect, in: NSTextContainer) -> NSRange

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

func glyphRange(forBoundingRectWithoutAdditionalLayout: CGRect, in: NSTextContainer) -> NSRange

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

func glyphRange(for: NSTextContainer) -> NSRange

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

func glyphRange(forCharacterRange: NSRange, actualCharacterRange: NSRangePointer?) -> NSRange

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

func range(ofNominallySpacedGlyphsContaining: Int) -> NSRange

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

Drawing

func drawBackground(forGlyphRange: NSRange, at: CGPoint)

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

func drawGlyphs(forGlyphRange: NSRange, at: CGPoint)

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

func underlineGlyphRange(NSRange, underlineType: NSUnderlineStyle, lineFragmentRect: CGRect, lineFragmentGlyphRange: NSRange, containerOrigin: CGPoint)

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.

Handling Layout for Text Blocks

func setLayoutRect(NSRect, for: NSTextBlock, glyphRange: NSRange)

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

func layoutRect(for: NSTextBlock, glyphRange: NSRange) -> NSRect

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

func setBoundsRect(NSRect, for: NSTextBlock, glyphRange: NSRange)

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

func boundsRect(for: NSTextBlock, glyphRange: NSRange) -> NSRect

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

func layoutRect(for: NSTextBlock, at: Int, effectiveRange: NSRangePointer?) -> NSRect

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

func boundsRect(for: NSTextBlock, at: Int, effectiveRange: NSRangePointer?) -> NSRect

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

Managing Attachments

var defaultAttachmentScaling: NSImageScaling

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

Managing the Responder Chain

func layoutManagerOwnsFirstResponder(in: NSWindow) -> Bool

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

var firstTextView: NSTextView?

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

var textViewForBeginningOfSelection: NSTextView?

The text view containing the first glyph in the selection.

Managing the Typesetter

var typesetter: NSTypesetter

The current typesetter.

enum NSLayoutManager.TypesetterBehavior

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

func defaultLineHeight(for: NSFont) -> CGFloat

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

func defaultBaselineOffset(for: NSFont) -> CGFloat

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

Managing Temporary Attribute Support

func addTemporaryAttributes([NSAttributedString.Key : Any], forCharacterRange: NSRange)

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

func addTemporaryAttribute(NSAttributedString.Key, value: Any, forCharacterRange: NSRange)

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

func setTemporaryAttributes([NSAttributedString.Key : Any], forCharacterRange: NSRange)

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

func removeTemporaryAttribute(NSAttributedString.Key, forCharacterRange: NSRange)

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

func temporaryAttribute(NSAttributedString.Key, atCharacterIndex: Int, effectiveRange: NSRangePointer?) -> Any?

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

func temporaryAttribute(NSAttributedString.Key, atCharacterIndex: Int, longestEffectiveRange: NSRangePointer?, in: NSRange) -> Any?

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

func temporaryAttributes(atCharacterIndex: Int, effectiveRange: NSRangePointer?) -> [NSAttributedString.Key : Any]

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

func temporaryAttributes(atCharacterIndex: Int, longestEffectiveRange: NSRangePointer?, in: NSRange) -> [NSAttributedString.Key : Any]

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.

Enumerations

enum NSLayoutManager.TextLayoutOrientation

Describes the text layout orientation.

See Also

Layout

protocol NSLayoutManagerDelegate

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

protocol NSTextLayoutOrientationProvider

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