Class

NSLayoutManager

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.

Overview

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.

Symbols

Initializing the Layout Manager

init()

Initializes the receiver, a newly created NSLayoutManager object.

Accessing the Text Storage

var textStorage: NSTextStorage?

The receiver’s NSTextStorage object.

func replaceTextStorage(NSTextStorage)

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

Accessing the Delegate

var delegate: NSLayoutManagerDelegate?

The receiver’s delegate.

Managing the Text Containers

var textContainers: [NSTextContainer]

The receiver’s text containers.

func addTextContainer(NSTextContainer)

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

func insertTextContainer(NSTextContainer, at: Int)

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

func removeTextContainer(at: Int)

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

func setTextContainer(NSTextContainer, forGlyphRange: NSRange)

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

func textContainerChangedGeometry(NSTextContainer)

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

func textContainerChangedTextView(NSTextContainer)

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

func textContainer(forGlyphAt: Int, effectiveRange: NSRangePointer?)

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.

func textContainer(forGlyphAt: Int, effectiveRange: NSRangePointer?, withoutAdditionalLayout: Bool)

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.

func usedRect(for: NSTextContainer)

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

Configuring the Global Layout Manager Options

var allowsNonContiguousLayout: Bool

A boolean that enables or disables noncontiguous layout.

var hasNonContiguousLayout: Bool

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

var hyphenationFactor: CGFloat

The threshold controlling when hyphenation is done.

var showsInvisibleCharacters: Bool

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

var showsControlCharacters: Bool

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

var usesFontLeading: Bool

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

var backgroundLayoutEnabled: Bool

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

func invalidateDisplay(forCharacterRange: NSRange)

Invalidates display for the given character range.

func invalidateDisplay(forGlyphRange: NSRange)

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 setNeedsDisplay(_:)).

func invalidateGlyphs(forCharacterRange: NSRange, changeInLength: Int, actualCharacterRange: NSRangePointer?)

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.

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

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

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 this layout manager.

Accessing Glyphs

func characterIndexForGlyph(at: Int)

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

func glyphIndexForCharacter(at: Int)

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

func isValidGlyphIndex(Int)

Indicates whether the specified index refers to a valid glyph, otherwise false.

var numberOfGlyphs: Int

The number of glyphs in the receiver.

func propertyForGlyph(at: Int)

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

Setting Layout Information

func setAttachmentSize(CGSize, forGlyphRange: NSRange)

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

func setDrawsOutsideLineFragment(Bool, forGlyphAt: Int)

Specifies whether the given glyph exceeds the bounds of the line fragment where 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 given line fragment bounds with the given range of glyphs.

func setLocation(CGPoint, forStartOfGlyphRange: NSRange)

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

func setNotShownAttribute(Bool, forGlyphAt: Int)

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

Getting Layout Information

func attachmentSize(forGlyphAt: Int)

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

func drawsOutsideLineFragment(forGlyphAt: Int)

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

var extraLineFragmentRect: CGRect

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

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.

var firstUnlaidCharacterIndex: Int

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

var 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?)

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.

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

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

func lineFragmentUsedRect(forGlyphAt: Int, effectiveRange: NSRangePointer?)

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.

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

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.

func location(forGlyphAt: Int)

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

func notShownAttribute(forGlyphAt: Int)

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

func truncatedGlyphRange(inLineFragmentForGlyphAt: Int)

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

Performing Advanced Layout Queries

func boundingRect(forGlyphRange: NSRange, in: NSTextContainer)

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.

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

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?)

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

func fractionOfDistanceThroughGlyph(for: CGPoint, in: NSTextContainer)

This method is a primitive for glyphIndex(for:in:fractionOfDistanceThroughGlyph:). You should always call the main method, not the primitives.

func glyphIndex(for: CGPoint, in: NSTextContainer)

This method is a primitive for glyphIndex(for:in:fractionOfDistanceThroughGlyph:). You should always call the main method, not the primitives.

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

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

func glyphRange(forBoundingRect: CGRect, in: NSTextContainer)

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

func glyphRange(forBoundingRectWithoutAdditionalLayout: CGRect, in: NSTextContainer)

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

func glyphRange(for: NSTextContainer)

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

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

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

func range(ofNominallySpacedGlyphsContaining: Int)

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

func drawBackground(forGlyphRange: NSRange, at: CGPoint)

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

func drawGlyphs(forGlyphRange: NSRange, at: CGPoint)

Draws the glyphs in the given glyph range, 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 glyphs in a given range and draws the underlining as appropriate.

Handling Layout for Text Blocks

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

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

func layoutRect(for: NSTextBlock, glyphRange: NSRange)

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

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

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

func boundsRect(for: NSTextBlock, glyphRange: NSRange)

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

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

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

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

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

Managing Attachments

var defaultAttachmentScaling: NSImageScaling

The default scaling behavior to the given scaling if an attachment image is too large to fit in a text container.

Handling Rulers

func rulerMarkers(for: NSTextView, paragraphStyle: NSParagraphStyle, ruler: NSRulerView)

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

Managing the Responder Chain

func layoutManagerOwnsFirstResponder(in: NSWindow)

Indicates whether the first responder in the given window is a text view associated with the receiver.

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.

var typesetterBehavior: NSTypesetterBehavior

The default typesetter behavior.

func defaultLineHeight(for: NSFont)

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

func defaultBaselineOffset(for: NSFont)

Returns the default baseline offset specified by the layout manager's typesetter behavior for the given font.

Managing Temporary Attribute Support

func addTemporaryAttributes([String : Any] = [:], forCharacterRange: NSRange)

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

func addTemporaryAttribute(String, value: Any, forCharacterRange: NSRange)

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

func setTemporaryAttributes([String : Any], forCharacterRange: NSRange)

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

func removeTemporaryAttribute(String, forCharacterRange: NSRange)

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

func temporaryAttribute(String, atCharacterIndex: Int, effectiveRange: NSRangePointer?)

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.

func temporaryAttribute(String, atCharacterIndex: Int, longestEffectiveRange: NSRangePointer?, in: NSRange)

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.

func temporaryAttributes(atCharacterIndex: Int, effectiveRange: NSRangePointer?)

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

func temporaryAttributes(atCharacterIndex: Int, longestEffectiveRange: NSRangePointer?, in: NSRange)

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.

func invalidateGlyphs(onLayoutInvalidationForGlyphRange: NSRange)

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

Deprecated
func invalidateLayout(forCharacterRange: NSRange, isSoft: Bool, actualCharacterRange: NSRangePointer?)

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

Deprecated
func textStorage(NSTextStorage, edited: NSTextStorageEditedOptions, range: NSRange, changeInLength: Int, invalidatedRange: NSRange)

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

Deprecated
func insertGlyph(NSGlyph, atGlyphIndex: Int, characterIndex: Int)

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

Deprecated
func glyph(at: Int)

Returns the glyph at glyphIndex.

Deprecated
func glyph(at: Int, isValidIndex: UnsafeMutablePointer<ObjCBool>?)

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
func replaceGlyph(at: Int, withGlyph: NSGlyph)

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

Deprecated
func getGlyphs(UnsafeMutablePointer<NSGlyph>?, range: NSRange)

Fills the passed-in buffer with a sequence of glyphs

Deprecated
func deleteGlyphs(in: NSRange)

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

Deprecated
func setCharacterIndex(Int, forGlyphAt: Int)

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

Deprecated
func intAttribute(Int, forGlyphAt: Int)

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

Deprecated
func rectArray(forCharacterRange: NSRange, withinSelectedCharacterRange: NSRange, in: NSTextContainer, rectCount: UnsafeMutablePointer<Int>)

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
func rectArray(forGlyphRange: NSRange, withinSelectedGlyphRange: NSRange, in: NSTextContainer, rectCount: UnsafeMutablePointer<Int>)

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.

var usesScreenFonts: Bool

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

Deprecated
func substituteFont(for: NSFont)

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

Deprecated

Constants

Glyph Attributes

These glyph attribute constants are used only inside the glyph generation machinery, but they must be shared between components.

NSTextLayoutOrientation

Describes the text layout orientation.

NSGlyphProperty

Describes glyph properties.

NSControlCharacterAction

Describes actions control characters can cause.

NSGlyphInscription

These constants specify how a glyph is laid out relative to the previous glyph. The glyph inscription constants are possible values for the glyph attribute NSGlyphAttributeInscribe. Glyph inscriptions are set during glyph generation.

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