---

NSLayoutManager

Overview

An NSLayoutManager 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 NSTextContainers, and displays them in a series of NSTextViews. In addition to its core function of laying out text, an NSLayoutManager coordinates its NSTextViews, provides services to those NSTextViews to support NSRulerViews 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.

NSLayoutManager now 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 System Preferences application’s General pane.

Tasks

Constructors

• NSLayoutManager

Setting the Text Storage

• setTextStorage
• textStorage
• replaceTextStorage

Setting Text Containers

• textContainers
• addTextContainer
• insertTextContainerAtIndex
• removeTextContainerAtIndex

Invalidating Glyphs and Layout

• invalidateGlyphsForCharacterRange
• invalidateLayoutForCharacterRange
• invalidateDisplayForCharacterRange
• invalidateDisplayForGlyphRange
• textContainerChangedGeometry
• textContainerChangedTextView
• textStorageChanged

Turning Background Layout On/off

• setBackgroundLayoutEnabled
• backgroundLayoutEnabled

Accessing Glyphs

• insertGlyphAtGlyphIndex
• isValidGlyphIndex
• glyphAtIndex
• replaceGlyphAtIndex
• glyphsInRange
• deleteGlyphsInRange
• numberOfGlyphs

Mapping Characters to Glyphs

• setCharacterIndexForGlyphAtIndex
• characterIndexForGlyphAtIndex
• characterRangeForGlyphRange
• glyphRangeForCharacterRange

Setting Glyph Attributes

• setGlyphAttributeForGlyphAtIndex
• glyphAttributeForGlyphAtIndex
• setDefaultAttachmentScaling
• defaultAttachmentScaling
• showAttachmentCell

Handling Layout for Text Containers

• setTextContainerForGlyphRange
• glyphRangeForTextContainer
• textContainerForGlyphAtIndex
• usedRectForTextContainer

Handling Line Fragment Rectangles

• setLineFragmentRectForGlyphAtIndex
• lineFragmentRectForGlyphAtIndex
• lineFragmentUsedRectForGlyphAtIndex
• setExtraLineFragmentRect
• extraLineFragmentRect
• extraLineFragmentUsedRect
• extraLineFragmentTextContainer
• setDrawsOutsideLineFragmentForGlyphAtIndex
• drawsOutsideLineFragmentForGlyphAtIndex

Layout of Glyphs

• setLocationForStartOfGlyphRange
• locationForGlyphAtIndex
• rangeOfNominallySpacedGlyphsContainingIndex
• rectArrayForCharacterRange
• rectArrayForGlyphRange
• boundingRectForGlyphRange
• glyphRangeForBoundingRect
• glyphRangeForBoundingRectWithoutAdditionalLayout
• fractionOfDistanceThroughGlyphForPoint
• glyphIndexForPoint

Handling Layout for Text Blocks

• setLayoutRect
• layoutRectForTextBlock
• setBoundsRect
• boundsRectForTextBlock
• layoutRectForTextBlockAtIndex
• boundsRectForTextBlockAtIndex

Display of Special Glyphs

• setNotShownForGlyphAtIndex
• notShownAttributeForGlyphAtIndex
• setShowsInvisibleCharacters
• showsInvisibleCharacters
• setShowsControlCharacters
• showsControlCharacters

Controlling Hyphenation

• setHyphenationFactor
• hyphenationFactor

Finding Unlaid Characters and Glyphs

• firstUnlaidCharacterIndex
• firstUnlaidGlyphIndex

Using Screen Fonts

• setUsesScreenFonts
• usesScreenFonts
• substituteFontForFont

Handling Rulers

• rulerAccessoryViewForTextView
• rulerMarkersForTextView

Managing the Responder Chain

• layoutManagerOwnsFirstResponderInWindow
• firstTextView
• textViewForBeginningOfSelection

Drawing

• drawBackgroundForGlyphRange
• drawGlyphsForGlyphRange
• drawUnderlineForGlyphRange
• underlineGlyphRange
• drawStrikethroughForGlyphRange
• strikethroughGlyphRange

Setting the Delegate

• setDelegate
• delegate

Typesetter Compatibility

• defaultLineHeightForFont
• setTypesetterBehavior
• typesetterBehavior

Temporary Attribute Support

• addTemporaryAttributes
• removeTemporaryAttribute
• setTemporaryAttributes
• temporaryAttributesAtCharacterIndex

Laying out text

• layoutManagerDidCompleteLayoutForTextContainer  delegate method
• layoutManagerDidInvalidateLayout  delegate method

Instance Methods

addTemporaryAttributes

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

public void addTemporaryAttributes(NSDictionary attrs, NSRange charRange)

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 that will be recognized are those related to colors and underlines.

See Also

• setTemporaryAttributes
• removeTemporaryAttribute
• temporaryAttributesAtCharacterIndex

addTextContainer

Appends aTextContainer to the series of NSTextContainers where the receiver arranges text.

public void addTextContainer(NSTextContainer aTextContainer)

Discussion

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

See Also

• insertTextContainerAtIndex
• removeTextContainerAtIndex
• textContainers
• invalidateGlyphsForCharacterRange
• invalidateLayoutForCharacterRange

backgroundLayoutEnabled

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

public boolean backgroundLayoutEnabled()

See Also

• setBackgroundLayoutEnabled

boundingRectForGlyphRange

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

public NSRect boundingRectForGlyphRange(NSRange glyphRange, NSTextContainer aTextContainer)

Discussion

This method is useful for determining the area that needs to be redrawn when a range of glyphs changes.

Performs glyph generation and layout if needed.

See Also

• glyphRangeForTextContainer
• drawsOutsideLineFragmentForGlyphAtIndex

boundsRectForTextBlock

Returns the bounding rectangle enclosing a text block block containing the glyph range glyphRange.

public NSRect boundsRectForTextBlock(NSTextBlock block, NSRange glyphRange)

Discussion

This method causes glyph generation but not layout. It returns ZeroRect if no rectangle has been set for the specified block since the last invalidation.

Availability

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

See Also

• setBoundsRect

boundsRectForTextBlockAtIndex

Returns the bounding rectangle enclosing a text block block containing the glyph at glyphIndex.

public NSRect boundsRectForTextBlockAtIndex(NSTextBlock block, int glyphIndex, NSMutableRange effectiveGlyphRange)

Discussion

The effectiveGlyphRange is set to contain the range for all glyphs in the text block. This method causes glyph generation but not layout. It returns ZeroRect if no rectangle has been set for the specified block since the last invalidation.

Availability

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

See Also

• setBoundsRect

characterIndexForGlyphAtIndex

Returns the index in the NSTextStorage for the first character mapped to the glyph at glyphIndex within the receiver.

public int characterIndexForGlyphAtIndex(int glyphIndex)

Discussion

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

Performs glyph generation if needed.

characterRangeForGlyphRange

Returns the range for the characters in the receiver’s text store that are mapped to the glyphs in glyphRange.

public NSRange characterRangeForGlyphRange(NSRange glyphRange, NSMutableRange actualGlyphRange)

Discussion

If actualGlyphRange is non-null, expands the requested range as needed so that it identifies all glyphs mapped to those characters and returns the new range by reference in actualGlyphRange.

Suppose the text store begins with the character “Ö” and the glyph cache contains “O” and “¨”. If you get the character range for the glyph range {0, 1} or {1, 1}, actualGlyphRange is returned as {0, 2}, indicating that both glyphs are mapped to the character “Ö”.

Performs glyph generation if needed.

See Also

• characterIndexForGlyphAtIndex
• glyphRangeForCharacterRange

defaultAttachmentScaling

Returns the default behavior desired if an attachment image is too large to fit in a text container.

public int defaultAttachmentScaling()

Discussion

Note that attachment cells control their own size and drawing, so this setting can only be advisory for them, but Application Kit–supplied attachment cells will respect it.

See Also

• setDefaultAttachmentScaling

defaultLineHeightForFont

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

public float defaultLineHeightForFont(NSFont theFont)

Discussion

This value may vary according to the typesetter behavior.

Availability

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

See Also

• setTypesetterBehavior

delegate

Returns the receiver’s delegate.

public Object delegate()

See Also

• setDelegate

deleteGlyphsInRange

Deletes the glyphs in glyphRange.

public void deleteGlyphsInRange(NSRange glyphRange)

Discussion

This method is for use by the glyph-generation mechanism and doesn’t perform any invalidation or generation of the glyphs or layout. You should never directly invoke this method.

See Also

• insertGlyphAtGlyphIndex

drawBackgroundForGlyphRange

Draws background marks for glyphRange, which must lie completely within a single NSTextContainer.

public void drawBackgroundForGlyphRange(NSRange glyphRange, NSPoint containerOrigin)

Discussion

containerOrigin indicates the position of the NSTextContainer in the coordinate system of the NSView being drawn. This method must be invoked with the graphics focus locked on that NSView.

Background marks are such things as selection highlighting, text background color, and any background for marked text.

Performs glyph generation and layout if needed.

See Also

• drawGlyphsForGlyphRange
• glyphRangeForTextContainer
• textContainerOrigin (NSTextView)

drawGlyphsForGlyphRange

Draws the glyphs in glyphRange, which must lie completely within a single NSTextContainer.

public void drawGlyphsForGlyphRange(NSRange glyphRange, NSPoint containerOrigin)

Discussion

containerOrigin indicates the position of the NSTextContainer in the coordinate system of the NSView being drawn. This method expects the coordinate system of the view to be flipped. This method must be invoked with the graphics focus locked on that NSView.

Performs glyph generation and layout if needed.

See Also

• drawBackgroundForGlyphRange
• glyphRangeForTextContainer
• textContainerOrigin (NSTextView)

drawsOutsideLineFragmentForGlyphAtIndex

Returns true if the glyph at glyphIndex exceeds the bounds of the line fragment where it’s laid out, false otherwise.

public boolean drawsOutsideLineFragmentForGlyphAtIndex(int glyphIndex)

Discussion

Exceeding bounds can happen when text is set at a fixed line height. For example, if the user specifies a fixed line height of 12 points and sets the font size to 24 points, the glyphs will exceed their layout rectangles.

Glyphs that draw outside their line fragment rectangles aren’t considered when calculating enclosing rectangles with the rectArrayForCharacterRange and rectArrayForGlyphRange methods. They are, however, considered by boundingRectForGlyphRange.

Performs glyph generation and layout if needed.

drawStrikethroughForGlyphRange

Draws strikethrough for the glyphs in glyphRange, which must belong to a single line fragment rectangle (as returned by lineFragmentRectForGlyphAtIndex).

public void drawStrikethroughForGlyphRange(NSRange glyphRange, int strikethroughVal, float baselineOffset, NSRect lineRect, NSRange lineGlyphRange, NSPoint containerOrigin)

Discussion

strikethroughVal indicates the style of strikethrough to draw. baselineOffset indicates how far above the text baseline the underline should be drawn (usually a negative value). lineRect is the line fragment rectangle containing the glyphs to draw strikethrough for, and lineGlyphRange is the range of all glyphs within that line fragment rectangle. containerOrigin is the origin of the line fragment rectangle’s NSTextContainer in its NSTextView.

This method is invoked automatically by strikethroughGlyphRange; you should rarely need to invoke it directly.

Availability

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

drawUnderlineForGlyphRange

Draws underlining for the glyphs in glyphRange, which must belong to a single line fragment rectangle (as returned by lineFragmentRectForGlyphAtIndex).

public void drawUnderlineForGlyphRange(NSRange glyphRange, int underlineType, float baselineOffset, NSRect lineRect, NSRange lineGlyphRange, NSPoint containerOrigin)

Discussion

underlineType indicates the style of underlining to draw; NSLayoutManager accepts only NSAttributedString.SingleUnderlineStyle, but subclasses can define their own underline styles. baselineOffset indicates how far below the text baseline the underline should be drawn; it’s usually a positive value. lineRect is the line fragment rectangle containing the glyphs to draw underlining for, and lineGlyphRange is the range of all glyphs within that line fragment rectangle. containerOrigin is the origin of the line fragment rectangle’s NSTextContainer in its NSTextView.

This method is invoked automatically by underlineGlyphRange; you should rarely need to invoke it directly.

See Also

• textContainerForGlyphAtIndex
• textContainerOrigin (NSTextView)

extraLineFragmentRect

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

public NSRect extraLineFragmentRect()

Discussion

The rectangle is defined in the coordinate system of its NSTextContainer. Returns NSRect.ZeroRect if there is no such rectangle.

See Also

• extraLineFragmentUsedRect
• extraLineFragmentTextContainer
• setExtraLineFragmentRect

extraLineFragmentTextContainer

Returns the NSTextContainer that contains the extra line fragment rectangle, or null if there is no extra line fragment rectangle.

public NSTextContainer extraLineFragmentTextContainer()

Discussion

This rectangle is used to display the insertion point at the end of a text (either in an empty text or after a final paragraph separator).

See Also

• extraLineFragmentRect
• extraLineFragmentUsedRect
• setExtraLineFragmentRect

extraLineFragmentUsedRect

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

public NSRect extraLineFragmentUsedRect()

Discussion

The rectangle is defined in the coordinate system of its NSTextContainer. Returns NSRect.ZeroRect if there is no extra line fragment rectangle.

The extra line fragment used rectangle is twice as wide (or tall) as the NSTextContainer’s line fragment padding, with the insertion point itself in the middle.

See Also

• extraLineFragmentRect
• extraLineFragmentTextContainer
• setExtraLineFragmentRect

firstTextView

Returns the first NSTextView in the receiver’s series of text views.

public NSTextView firstTextView()

Discussion

This NSTextView is the object of various NSText and NSTextView notifications posted.

firstUnlaidCharacterIndex

Returns the index for the first unlaid character in the layout manager.

public int firstUnlaidCharacterIndex()

firstUnlaidGlyphIndex

Returns the index for the first unlaid glyph in the layout manager.

public int firstUnlaidGlyphIndex()

fractionOfDistanceThroughGlyphForPoint

Returns the ratio of the distance into the glyph relative to the next glyph (in the appropriate sweep direction).

public float fractionOfDistanceThroughGlyphForPoint(NSPoint aPoint, NSTextContainer aTextContainer)

Discussion

NSLayoutManager currently supports only left-to-right sweep. aPoint is expressed in the coordinate system of aTextContainer.

For purposes such as dragging out a selection or placing the insertion point, a return value less than or equal to 0.5 indicates that aPoint should be considered as falling before the glyph index returned by glyphIndexForPoint for the specified point. A return value greater than 0.5 indicates that it should be considered as falling after the glyph index returned by glyphIndexForPoint. If the nearest glyph doesn’t lie under aPoint at all (for example, if aPoint is beyond the beginning or end of a line), this ratio will be 0 or 1.

Suppose the glyph stream contains the glyphs “A” and “b”, with the width of “A” being 13 points. If the user clicks at a location 8 points into “A”, the return value is 8/13, or 0.615. In this case, the point given should be considered as falling between “A” and “b” for purposes such as dragging out a selection or placing the insertion point.

Performs glyph generation and layout if needed.

See Also

• glyphIndexForPoint

glyphAtIndex

Returns the glyph at glyphIndex.

public int glyphAtIndex(int glyphIndex)

Discussion

Throws a RangeException if glyphIndex is out of bounds.

Performs glyph generation if needed. To avoid an exception with glyphAtIndex you must first check the glyph index against the number of glyphs, which requires generating all glyphs.

glyphAttributeForGlyphAtIndex

Returns the value of the attribute identified by attributeTag for the glyph at glyphIndex.

public int glyphAttributeForGlyphAtIndex(int attributeTag, int glyphIndex)

Discussion

Subclasses that define their own custom attributes must override this method to access their own storage for the attribute values. Nonnegative tags are reserved by Apple; you can define your own attributes with negative tags and set values using setGlyphAttributeForGlyphAtIndex.

glyphIndexForPoint

Returns the index for the glyph nearest aPoint within aTextContainer.

public int glyphIndexForPoint(NSPoint aPoint, NSTextContainer aTextContainer)

Discussion

aPoint is expressed in the coordinate system of aTextContainer.

Performs glyph generation and layout if needed.

See Also

• fractionOfDistanceThroughGlyphForPoint

glyphRangeForBoundingRect

Returns the smallest contiguous range for glyphs that are laid out wholly or partially within aRect in aTextContainer.

public NSRange glyphRangeForBoundingRect(NSRect aRect, NSTextContainer aTextContainer)

Discussion

The range returned can include glyphs that don’t fall inside or intersect aRect, though the first and last glyphs in the range always do. This method is used to determine which glyphs need to be displayed within a given rectangle.

Performs glyph generation and layout if needed.

See Also

• glyphRangeForBoundingRectWithoutAdditionalLayout

glyphRangeForBoundingRectWithoutAdditionalLayout

Returns the smallest contiguous range for glyphs that are laid out wholly or partially within bounds in aTextContainer.

public NSRange glyphRangeForBoundingRectWithoutAdditionalLayout(NSRect bounds, NSTextContainer container)

Discussion

The range returned can include glyphs that don’t fall inside or intersect aRect, though the first and last glyphs in the range always do.

Unlike glyphRangeForBoundingRect, this method doesn’t perform glyph generation or layout. Its results, though faster, can be incorrect. This method is primarily for use by NSTextView; you should rarely need to use it yourself.

See Also

• glyphRangeForBoundingRect

glyphRangeForCharacterRange

Returns the range for the glyphs mapped to the characters of the text store in charRange.

public NSRange glyphRangeForCharacterRange(NSRange charRange, NSMutableRange actualCharRange)

Discussion

If actualCharRange is non-null, expands the requested range as needed so that it identifies all characters mapped to those glyphs and returns the new range by reference in actualCharRange.

Suppose the text store contains the characters “n˜”, and the glyph cache contains “ñ”. If you get the glyph range for the character range {0, 1} or {1, 1}, actualCharRange is returned as {0, 2}, indicating both of the characters mapped to the glyph “ñ”.

Performs glyph generation if needed.

See Also

• characterIndexForGlyphAtIndex

glyphRangeForTextContainer

Returns the range for glyphs laid out within aTextContainer.

public NSRange glyphRangeForTextContainer(NSTextContainer aTextContainer)

Discussion

Performs glyph generation and layout if needed.

glyphsInRange

Returns displayable glyphs from glyphRange.

public int [] glyphsInRange(NSRange glyphRange)

Discussion

Throws a RangeException if the range specified exceeds the bounds of the actual glyph range for the receiver.

Performs glyph generation if needed.

See Also

• glyphAtIndex
• notShownAttributeForGlyphAtIndex

hyphenationFactor

public float hyphenationFactor()

Discussion

Whenever (width of the real contents of the line) / (the line fragment width) is less than hyphenationFactor, hyphenation will be attempted when laying out the line. The range of this factor is from 0.0 to 1.0. By default, the value is 0.0, meaning hyphenation is off. A value of 1.0 causes hyphenation to be attempted always. Note that hyphenation will slow down text layout and increase memory usage, so it should be used sparingly.

See Also

• setHyphenationFactor

insertGlyphAtGlyphIndex

Inserts aGlyph into the glyph cache at glyphIndex and maps it to the character at charIndex.

public void insertGlyphAtGlyphIndex(int aGlyph, int glyphIndex, int charIndex)

Discussion

If the glyph is mapped to several characters, charIndex should indicate the first character it’s mapped to.

This method is for use by the glyph-generation mechanism and doesn’t perform any invalidation or generation of the glyphs or layout. You should never directly invoke this method.

See Also

• deleteGlyphsInRange
• replaceGlyphAtIndex

insertTextContainerAtIndex

Inserts aTextContainer into the series of text containers at index and invalidates layout for all subsequent NSTextContainer’s.

public void insertTextContainerAtIndex(NSTextContainer aTextContainer, int index)

Discussion

Also invalidates glyph information as needed.

See Also

• addTextContainer
• removeTextContainerAtIndex
• textContainers

invalidateDisplayForCharacterRange

Invalidates display for charRange.

public void invalidateDisplayForCharacterRange(NSRange charRange)

Discussion

Unlaid parts of the range are remembered and will definitely be redisplayed at some point later when the layout is available. Does not actually cause layout.

invalidateDisplayForGlyphRange

Marks the glyphs in glyphRange as needing display, as well as the appropriate regions of the NSTextViews that display those glyphs (using NSView’s setNeedsDisplay).

public void invalidateDisplayForGlyphRange(NSRange glyphRange)

Discussion

You should rarely need to invoke this method.

invalidateGlyphsForCharacterRange

Invalidates the cached glyphs for the characters in charRange and adjusts the remaining glyph-to-character mapping according to lengthChange, which indicates the number of characters added to or removed from the text store.

public void invalidateGlyphsForCharacterRange(NSRange charRange, int lengthChange, NSMutableRange actualCharRange)

Discussion

If non-null, actualCharRange is set to the range of characters mapped to the glyphs just invalidated. This range can be larger than the range of characters given due to the effect of context on glyphs and layout.

You should rarely need to invoke this method. It only invalidates glyph information, and performs no glyph generation or layout. Because invalidating glyphs also invalidates layout, after invoking this method you should also invoke invalidateLayoutForCharacterRange, passing charRange as the first argument and false as the flag.

invalidateLayoutForCharacterRange

Invalidates the layout information for the glyphs mapped to the characters in charRange.

public void invalidateLayoutForCharacterRange(NSRange charRange, boolean flag, NSMutableRange actualCharRange)

Discussion

If flag is true, attempts to save some layout information to avoid recalculation; if flag is false, saves no layout information. You should typically pass false for flag. If non-null, actualCharRange is set to the range of characters mapped to the glyphs whose layout information has been invalidated. This range can be larger than the range of characters given due to the effect of context on glyphs and layout.

This method only invalidates information; it performs no glyph generation or layout. You should rarely need to invoke this method.

See Also

• invalidateGlyphsForCharacterRange

isValidGlyphIndex

Returns true if the specified glyphIndex refers to a valid glyph, otherwise false.

public boolean isValidGlyphIndex(int glyphIndex)

layoutManagerOwnsFirstResponderInWindow

Returns true if the first responder in aWindow is an NSTextView associated with the receiver, false otherwise.

public boolean layoutManagerOwnsFirstResponderInWindow(NSWindow aWindow)

layoutRectForTextBlock

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

public NSRect layoutRectForTextBlock(NSTextBlock block, NSRange glyphRange)

Discussion

This method causes glyph generation but not layout. It returns ZeroRect if no rectangle has been set for the specified block since the last invalidation.

Availability

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

See Also

• setLayoutRect

layoutRectForTextBlockAtIndex

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

public NSRect layoutRectForTextBlockAtIndex(NSTextBlock block, int glyphIndex, NSMutableRange effectiveGlyphRange)

Discussion

The effectiveGlyphRange is set to contain the range for all glyphs in the text block. This method causes glyph generation but not layout. It returns ZeroRect if no rectangle has been set for the specified block since the last invalidation.

Availability

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

See Also

• setLayoutRect

lineFragmentRectForGlyphAtIndex

public NSRect lineFragmentRectForGlyphAtIndex(int glyphIndex, NSMutableRange effectiveGlyphRange)

Returns the line fragment rectangle containing the glyph at glyphIndex.

public NSRect lineFragmentRectForGlyphAtIndex(int glyphIndex, NSMutableRange effectiveGlyphRange, boolean flag)

Discussion

The rectangle is defined in the coordinate system of its NSTextContainer. If non-null, effectiveGlyphRange is set to contain the range for all glyphs in that line fragment.

Performs glyph generation if needed. For the variant method with the Boolean argument flag, if flag is true, the method performs no additional layout so as to avoid an infinite recursion.

Availability

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

See Also

• setLineFragmentRectForGlyphAtIndex
• lineFragmentUsedRectForGlyphAtIndex

lineFragmentUsedRectForGlyphAtIndex

Returns the portion of the line fragment rectangle containing glyphIndex that actually contains glyphs (such as for a partial or wrapped line), plus the line fragment padding defined by the NSTextContainer where the glyphs reside.

public NSRect lineFragmentUsedRectForGlyphAtIndex(int glyphIndex, NSMutableRange effectiveGlyphRange)

Returns the portion of the line fragment rectangle containing glyphIndex that actually contains glyphs (such as for a partial or wrapped line), plus the line fragment padding defined by the NSTextContainer where the glyphs reside. If flag is true, performs no additional layout so as to avoid an infinite recursion.

public NSRect lineFragmentUsedRectForGlyphAtIndex(int glyphIndex, NSMutableRange effectiveGlyphRange, boolean flag)

Discussion

This rectangle is defined in the coordinate system of its NSTextContainer, and is based on line calculation only—that is, it isn’t a bounding box for the glyphs in the line fragment.

If non-null, effectiveGlyphRange is set to contain the range for all glyphs in the line fragment.

Performs glyph generation if needed.

Availability

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

See Also

• setLineFragmentRectForGlyphAtIndex
• lineFragmentRectForGlyphAtIndex

locationForGlyphAtIndex

Returns the location, in terms of its line fragment rectangle, for the glyph at glyphIndex.

public NSPoint locationForGlyphAtIndex(int glyphIndex)

Discussion

The line fragment rectangle in turn is defined in the coordinate system of the text container where it resides.

Performs glyph generation and layout if needed.

See Also

• lineFragmentRectForGlyphAtIndex
• lineFragmentUsedRectForGlyphAtIndex

notShownAttributeForGlyphAtIndex

Returns true if the glyph at glyphIndex isn’t shown (in the sense of the PostScript show operator), false if it is.

public boolean notShownAttributeForGlyphAtIndex(int glyphIndex)

Discussion

For example, a tab, newline, or attachment glyph doesn’t get shown; it just affects the layout of following glyphs or locates the attachment graphic. Space characters, however, typically are shown as glyphs with a displacement, though they leave no visible marks. Throws a RangeException if glyphIndex is out of bounds.

Performs glyph generation and layout if needed.

See Also

• setNotShownForGlyphAtIndex

numberOfGlyphs

Returns the number of glyphs in the receiver, performing glyph generation if needed to determine this number.

public int numberOfGlyphs()

rangeOfNominallySpacedGlyphsContainingIndex

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

public NSRange rangeOfNominallySpacedGlyphsContainingIndex(int glyphIndex)

Discussion

Performs glyph generation and layout if needed.

rectArrayForCharacterRange

Returns a rectangle for the glyphs in aTextContainer that correspond to charRange.

public NSRect rectArrayForCharacterRange(NSRange charRange, NSRange selCharRange, NSTextContainer aTextContainer)

Discussion

This rectangles can be used to draw the background or highlight for the given range of characters. selCharRange indicates selected characters, which can affect the size of the rectangles; it must be equal to or contain charRange. To calculate the rectangles for drawing the background, use a selected character range whose location is NSArray.NotFound. To calculate the rectangles for drawing highlighting for charRange, use a selected character range that contains charRange.

The number of rectangles returned isn’t necessarily the number of lines enclosing the specified range. Contiguous lines can share an enclosing rectangle, and lines broken into several fragments have a separate enclosing rectangle for each fragment.

The rectangle returned is owned by the receiver, and is overwritten by various NSLayoutManager methods. You should never free it and should copy it if you need to keep the values or use them after sending other messages to the layout manager.

The purpose of this method is to calculate line rectangles for drawing the text background and highlighting. These rectangles don’t necessarily enclose glyphs that draw outside their line fragment rectangles; use boundingRectForGlyphRange to determine the area that contains all drawing performed for a range of glyphs.

Performs glyph generation and layout if needed.

See Also

• glyphRangeForTextContainer
• characterRangeForGlyphRange
• drawsOutsideLineFragmentForGlyphAtIndex

rectArrayForGlyphRange

Returns a rectangle for the glyphs in aTextContainer in glyphRange.

public NSRect rectArrayForGlyphRange(NSRange glyphRange, NSRange selGlyphRange, NSTextContainer aTextContainer)

Discussion

This rectangles can be used to draw the background or highlight for the given range of glyphs. selGlyphRange indicates selected glyphs. To calculate the rectangles for drawing the background, use a selected glyph range whose location is NSArray.NotFound. To calculate the rectangles for highlighting, use a selected glyph range that contains glyphRange.

The number of rectangles returned isn’t necessarily the number of lines enclosing the specified range. Contiguous lines can share an enclosing rectangle, and lines broken into several fragments have a separate enclosing rectangle for each fragment.

The rectangle returned is owned by the receiver and is overwritten by various NSLayoutManager methods. You should never free it and should copy it if you need to keep the values or use them after sending other messages to the layout manager.

The purpose of this method is to calculate line rectangles for drawing the text background and highlighting. These rectangles don’t necessarily enclose glyphs that draw outside their line fragment rectangles; use boundingRectForGlyphRange to determine the area that contains all drawing performed for a range of glyphs.

Performs glyph generation and layout if needed.

See Also

• glyphRangeForTextContainer
• drawsOutsideLineFragmentForGlyphAtIndex

removeTemporaryAttribute

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

public void removeTemporaryAttribute(String name, NSRange charRange)

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 that will be recognized are those related to colors and underlines.

See Also

• setTemporaryAttributes
• addTemporaryAttributes
• temporaryAttributesAtCharacterIndex

removeTextContainerAtIndex

Removes the NSTextContainer at index and invalidates the layout as needed.

public void removeTextContainerAtIndex(int index)

Discussion

Also invalidates glyph information as needed.

See Also

• addTextContainer
• insertTextContainerAtIndex
• textContainers
• invalidateGlyphsForCharacterRange
• invalidateLayoutForCharacterRange

replaceGlyphAtIndex

Replaces the glyph at glyphIndex with newGlyph.

public void replaceGlyphAtIndex(int glyphIndex, int newGlyph)

Discussion

Doesn’t alter the glyph-to-character mapping or invalidate layout information.

This method is for use by the glyph-generation mechanism and doesn’t perform any invalidation or generation of the glyphs or layout. You should never directly invoke this method.

See Also

• setCharacterIndexForGlyphAtIndex
• invalidateGlyphsForCharacterRange
• invalidateLayoutForCharacterRange

replaceTextStorage

Replaces the NSTextStorage for the group of text-system objects containing the receiver with newTextStorage.

public void replaceTextStorage(NSTextStorage newTextStorage)

Discussion

All NSLayoutManagers sharing the original NSTextStorage then share the new one. This method makes all the adjustments necessary to keep these relationships intact, unlike setTextStorage.

rulerAccessoryViewForTextView

Returns the accessory NSView for aRulerView in aTextView.

public NSView rulerAccessoryViewForTextView(NSTextView aTextView, NSParagraphStyle paraStyle, NSRulerView aRulerView, boolean flag)

Discussion

This accessory contains tab wells, text alignment buttons, and so on. paraStyle is used to set the state of the controls in the accessory NSView; it must not be null. If flag is true the accessory view is enabled and accepts mouse and keyboard events; if false it’s disabled.

This method is invoked automatically by the NSTextView object using the layout manager. You should rarely need to invoke it, but you can override it to customize ruler support. If you do this method directly, note that it neither installs the ruler accessory view nor sets the markers for the NSRulerView. You must install the accessory view into the ruler using NSRulerView’s setAccessoryView method. To set the markers, use rulerMarkersForTextView to get the markers needed and then send setMarkers to the ruler.

See Also

• horizontalRulerView (NSScrollView)

rulerMarkersForTextView

Returns the NSRulerMarkers for aRulerView in aTextView, based on paraStyle.

public NSArray rulerMarkersForTextView(NSTextView aTextView, NSParagraphStyle paraStyle, NSRulerView aRulerView)

Discussion

These markers represent such things as left and right margins, first-line indent, and tab stops. You can set these markers immediately with NSRulerView’s setMarkers method.

This method is invoked automatically by the NSTextView object using the layout manager. You should rarely need to invoke it, but you can override it to add new kinds of markers or otherwise customize ruler support.

See Also

• rulerAccessoryViewForTextView

setBackgroundLayoutEnabled

Sets whether the receiver generates glyphs and lays them out when the application’s run loop is idle according to flag.

public void setBackgroundLayoutEnabled(boolean flag)

See Also

• backgroundLayoutEnabled

setBoundsRect

Sets the bounding rectangle enclosing a text block block containing the glyph range glyphRange to rect.

public void setBoundsRect(NSRect rect, NSTextBlock block, NSRange glyphRange)

Discussion

This method causes glyph generation but not layout.

Availability

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

See Also

• boundingRectForGlyphRange
• boundsRectForTextBlockAtIndex
• boundsRectForTextBlock

setCharacterIndexForGlyphAtIndex

Maps the character at charIndex to the glyph at glyphIndex.

public void setCharacterIndexForGlyphAtIndex(int charIndex, int glyphIndex)

Discussion

This method is for use by the glyph-generation mechanism and doesn’t perform any invalidation or generation of the glyphs or layout. You should never directly invoke this method.

See Also

• characterIndexForGlyphAtIndex
• characterRangeForGlyphRange
• glyphRangeForCharacterRange

setDefaultAttachmentScaling

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

public void setDefaultAttachmentScaling(int scaling)

Discussion

Note that attachment cells control their own size and drawing, so this setting can only be advisory for them, but Application Kit–supplied attachment cells will respect it.

See Also

• defaultAttachmentScaling

setDelegate

Sets the receiver’s delegate to anObject.

public void setDelegate(Object anObject)

See Also

• delegate

setDrawsOutsideLineFragmentForGlyphAtIndex

Sets according to flag whether the glyph at glyphIndex exceeds the bounds of the line fragment where it’s laid out.

public void setDrawsOutsideLineFragmentForGlyphAtIndex(boolean flag, int glyphIndex)

Discussion

This can happen when text is set at a fixed line height. For example, if the user specifies a fixed line height of 12 points and sets the font size to 24 points, the glyphs will exceed their layout rectangles.

This method is used by the layout mechanism; you should never invoke it directly.

See Also

• drawsOutsideLineFragmentForGlyphAtIndex

setExtraLineFragmentRect

Sets a line fragment rectangle for displaying an empty last line in a body of text.

public void setExtraLineFragmentRect(NSRect aRect, NSRect usedRect, NSTextContainer aTextContainer)

Discussion

aRect is the rectangle to set, and aTextContainer is the NSTextContainer where the rectangle should be laid out. usedRect indicates where the insertion point is drawn.

This method is used by the layout mechanism; you should never invoke it directly.

See Also

• extraLineFragmentRect
• extraLineFragmentUsedRect
• textContainers

setGlyphAttributeForGlyphAtIndex

Sets a custom attribute value for the glyph at glyphIndex.

public void setGlyphAttributeForGlyphAtIndex(int attributeTag, int anInt, int glyphIndex)

Discussion

attributeTag identifies the custom attribute, and anInt is its new value.

Subclasses that define their own custom attributes must override this method and provide their own storage for the attribute values. Nonnegative tags are reserved; you can define your own attributes with negative tags and set values using this method.

This method doesn’t perform glyph generation or layout. The glyph at glyphIndex must already have been generated.

See Also

• glyphAttributeForGlyphAtIndex

setHyphenationFactor

Sets the threshold as to when hyphenation will be done.

public void setHyphenationFactor(float factor)

Discussion

factor is in the range of 0.0 to 1.0. Whenever (width of the real contents of the line) / (the line fragment width) is below factor, hyphenation will be attempted when laying out the line. By default, the value is 0.0, meaning hyphenation is off. A factor of 1.0 causes hyphenation to be attempted always. Note that hyphenation will slow down text layout and increase memory usage, so it should be used sparingly.

See Also

• hyphenationFactor

setLayoutRect

Sets the layout rectangle enclosing a text block block containing the glyph range glyphRange to rect.

public void setLayoutRect(NSRect rect, NSTextBlock block, NSRange glyphRange)

Discussion

This method causes glyph generation but not layout.

Availability

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

See Also

• layoutRectForTextBlockAtIndex
• layoutRectForTextBlock

setLineFragmentRectForGlyphAtIndex

Sets the line fragment rectangle where the glyphs in glyphRange are laid out to fragmentRect.

public void setLineFragmentRectForGlyphAtIndex(NSRect fragmentRect, NSRange glyphRange, NSRect usedRect)

Discussion

The text container must be specified first with setTextContainerForGlyphRange, and the exact positions of the glyphs must be set after the line fragment rectangle with setLocationForStartOfGlyphRange. usedRect indicates the portion of fragmentRect, in the NSTextContainer’s coordinate system, that actually contains glyphs or other marks that are drawn (including the text container’s line fragment padding). usedRect must be equal to or contained within fragmentRect.

This method is used by the layout mechanism; you should never invoke it directly.

See Also

• lineFragmentRectForGlyphAtIndex
• lineFragmentUsedRectForGlyphAtIndex

setLocationForStartOfGlyphRange

Sets the location where the glyphs in glyphRange are laid out to aPoint, which is expressed relative to the origin of the line fragment rectangle for glyphRange.

public void setLocationForStartOfGlyphRange(NSPoint aPoint, NSRange glyphRange)

Discussion

glyphRange defines a series of glyphs that can be displayed with a single PostScript show operation (a nominal range). Setting the location for a series of glyphs implies that the glyphs preceding it can’t be included in a single show operation.

Before setting the location for a glyph range, you must specify the text container with setTextContainerForGlyphRange and the line fragment rectangle with setLineFragmentRectForGlyphAtIndex.

This method is used by the layout mechanism; you should never invoke it directly.

See Also

• rangeOfNominallySpacedGlyphsContainingIndex

setNotShownForGlyphAtIndex

Sets according to flag whether the glyph at glyphIndex is one that isn’t shown.

public void setNotShownForGlyphAtIndex(boolean flag, int glyphIndex)

Discussion

For example, a tab or newline character doesn’t leave any marks; it just indicates where following glyphs are laid out. Throws a RangeException if glyphIndex is out of bounds.

This method is used by the layout mechanism; you should never invoke it directly.

See Also

• notShownAttributeForGlyphAtIndex

setShowsControlCharacters

Controls whether the receiver makes control characters visible in layout where possible.

public void setShowsControlCharacters(boolean flag)

Discussion

If flag is true, it substitutes visible glyphs for control characters if the font and script support it; if flag is false it doesn’t.

See Also

• setShowsInvisibleCharacters
• showsControlCharacters

setShowsInvisibleCharacters

Controls whether the receiver makes whitespace and other typically nonvisible characters visible in layout where possible.

public void setShowsInvisibleCharacters(boolean flag)

Discussion

If flag is true, it substitutes visible glyphs for invisible characters if the font and script support it; if flag is false it doesn’t.

See Also

• setShowsControlCharacters
• showsInvisibleCharacters

setTemporaryAttributes

Sets one or more temporary attributes passed in attrs for the character range specified in charRange.

public void setTemporaryAttributes(NSDictionary attrs, NSRange charRange)

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 that will be recognized are those related to colors and underlines.

See Also

• addTemporaryAttributes
• removeTemporaryAttribute
• temporaryAttributesAtCharacterIndex

setTextContainerForGlyphRange

Sets to aTextContainer the NSTextContainer where the glyphs in glyphRange are laid out.

public void setTextContainerForGlyphRange(NSTextContainer aTextContainer, NSRange glyphRange)

Discussion

You specify the layout within the container with the setLineFragmentRectForGlyphAtIndex and setLocationForStartOfGlyphRange methods.

This method is used by the layout mechanism; you should never invoke it directly.

See Also

• textContainerForGlyphAtIndex

setTextStorage

Sets the receiver’s NSTextStorage to textStorage.

public void setTextStorage(NSTextStorage textStorage)

Discussion

This method is invoked automatically when you add an NSLayoutManager to an NSTextStorage object; you should never need to invoke it directly, but might want to override it. If you want to replace the NSTextStorage for an established group of text-system objects containing the receiver, use replaceTextStorage.

See Also

• addLayoutManager (NSTextStorage)

setTypesetterBehavior

Sets according to theBehavior the default typesetter behavior, which affects glyph spacing and line height.

public void setTypesetterBehavior(int theBehavior)

Discussion

Possible values for theBehavior are described in “Constants.”

If the application was linked on a system prior to Mac OS X version 10.2, NSLayoutManager uses TypesetterOriginalBehavior by default.

Availability

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

See Also

• typesetterBehavior

setUsesScreenFonts

Sets according to flag whether the receiver calculates layout and displays text using screen fonts when possible.

public void setUsesScreenFonts(boolean flag)

See Also

• usesScreenFonts
• substituteFontForFont

showAttachmentCell

Actually draws an attachment cell.

public void showAttachmentCell(NSCell cell, NSRect rect, int attachmentIndex)

Discussion

The attachment passed in cell should be drawn within the given rect. attachmentIndex is provided for those cells that alter their appearance based on their location.

showsControlCharacters

Returns true if the receiver substitutes visible glyphs for control characters if the font and script support it, false if it doesn’t.

public boolean showsControlCharacters()

See Also

• showsInvisibleCharacters
• setShowsControlCharacters

showsInvisibleCharacters

Returns true if the receiver substitutes visible glyphs for invisible characters if the font and script support it, false if it doesn’t.

public boolean showsInvisibleCharacters()

See Also

• showsControlCharacters
• setShowsInvisibleCharacters

strikethroughGlyphRange

Calculates and draws strikethrough for the glyphs in glyphRange, which must belong to a single line fragment rectangle (as returned by lineFragmentRectForGlyphAtIndex).

public void strikethroughGlyphRange(NSRange glyphRange, int strikethroughVal, NSRect lineRect, NSRange lineGlyphRange, NSPoint containerOrigin)

Discussion

strikethroughVal indicates the style of strikethrough to draw. lineRect is the line fragment rectangle containing the glyphs to draw strikethrough for, and lineGlyphRange is the range of all glyphs within that line fragment rectangle. containerOrigin is the origin of the line fragment rectangle’s NSTextContainer in its NSTextView.

This method determines which glyphs actually need to be strikethrough based on strikethroughVal. After determining which glyphs to draw strikethrough on, this method invokes drawStrikethroughForGlyphRange for each contiguous range of glyphs that requires it.

Availability

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

substituteFontForFont

Returns a screen font suitable for use in place of originalFont, or simply returns originalFont if a screen font can’t be used or isn’t available.

public NSFont substituteFontForFont(NSFont originalFont)

Discussion

A screen font can be substituted if the receiver is set to use screen fonts and if no NSTextView associated with the receiver is scaled or rotated.

See Also

• usesScreenFonts

temporaryAttributesAtCharacterIndex

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

public NSDictionary temporaryAttributesAtCharacterIndex(int charIndex, NSMutableRange effectiveCharRange)

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 that will be recognized are those related to colors and underlines.

See Also

• addTemporaryAttributes
• removeTemporaryAttribute
• setTemporaryAttributes

textContainerChangedGeometry

Invalidates the layout information, and possibly glyphs, for aTextContainer and all subsequent NSTextContainers.

public void textContainerChangedGeometry(NSTextContainer aTextContainer)

Discussion

This method is invoked automatically by other components of the text system; you should rarely need to invoke it directly. Subclasses of NSTextContainer, however, must invoke this method any time their size of shape changes (a text container that dynamically adjusts its shape to wrap text around placed graphics, for example, must do so when a graphic is added, moved, or removed).

textContainerChangedTextView

Updates information needed to manage NSTextView objects in aTextContainer.

public void textContainerChangedTextView(NSTextContainer aTextContainer)

Discussion

This method is invoked automatically by other components of the text system; you should rarely need to invoke it directly.

textContainerForGlyphAtIndex

Returns the NSTextContainer where the glyph at glyphIndex is laid out.

public NSTextContainer textContainerForGlyphAtIndex(int glyphIndex, NSMutableRange effectiveGlyphRange)

Discussion

If non-null, effectiveGlyphRange is set to the range for all glyphs laid out in that text container.

Performs glyph generation and layout if needed.

See Also

• setTextContainerForGlyphRange

textContainers

Returns the receiver’s NSTextContainers.

public NSArray textContainers()

See Also

• addTextContainer
• insertTextContainerAtIndex
• removeTextContainerAtIndex

textStorage

Returns the receiver’s NSTextStorage.

public NSTextStorage textStorage()

See Also

• setTextStorage
• replaceTextStorage

textStorageChanged

Invalidates glyph and layout information for a portion of the text in aTextStorage.

public void textStorageChanged(NSTextStorage aTextStorage, int mask, NSRange range, int lengthChange, NSRange invalidatedCharRange)

Discussion

This message is sent from NSTextStorage’s processEditing method to indicate that its characters or attributes have been changed. This method invalidates glyphs and layout for the affected characters, and performs a soft invalidation of the layout information for all subsequent characters. mask specifies the nature of the changes. Its value is made by combining these options with the C bitwise OR operator:

The range argument indicates the extent of characters resulting from the edits. If the TextStorageEditedCharacters bit of mask is set, lengthChange gives the number of characters added to or removed from the original range (otherwise its value is irrelevant). For example, after replacing “The” with “Several” to produce the string “Several files couldn’t be saved”, range is {0, 7} and lengthChange is 4. The receiver uses this information to update its character-to-glyph mapping and to update the selection range based on the change.

The invalidatedCharRange argument represents the range of characters affected after attributes have been fixed. For example, deleting a paragraph separator character invalidates the layout information for all characters in the paragraphs that precede and follow the separator.

The textStorageChanged messages are sent in a series to each NSLayoutManager associated with the text storage object, so the NSLayoutManagers receiving them shouldn’t edit aTextStorage. If one of them does, the range, lengthChange, and invalidatedCharRange arguments will be incorrect for all following NSLayoutManagers that receive the message.

See Also

• invalidateLayoutForCharacterRange

textViewForBeginningOfSelection

Returns the NSTextView containing the first glyph in the selection, or null if there’s no selection or there isn’t enough layout information to determine the text view.

public NSTextView textViewForBeginningOfSelection()

typesetterBehavior

Returns the current typesetter behavior value.

public int typesetterBehavior()

Discussion

Possible return values are described in “Constants.”

Availability

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

See Also

• setTypesetterBehavior

underlineGlyphRange

Calculates and draws underlining for the glyphs in glyphRange, which must belong to a single line fragment rectangle (as returned by lineFragmentRectForGlyphAtIndex).

public void underlineGlyphRange(NSRange glyphRange, int underlineType, NSRect lineRect, NSRange lineGlyphRange, NSPoint containerOrigin)

Discussion

underlineType indicates the style of underlining to draw; NSLayoutManager accepts only NSAttributedString.SingleUnderlineStyle, but subclasses can define their own underline styles. lineRect is the line fragment rectangle containing the glyphs to draw underlining for, and lineGlyphRange is the range of all glyphs within that line fragment rectangle. containerOrigin is the origin of the line fragment rectangle’s NSTextContainer in its NSTextView.

This method determines which glyphs actually need to be underlined based on underlineType. With NSAttributedString.SingleUnderlineStyle, for example, leading and trailing whitespace isn’t underlined, but whitespace between visible glyphs is. A potential word-underline style would omit underlining on any whitespace. After determining which glyphs to draw underlining on, this method invokes drawUnderlineForGlyphRange for each contiguous range of glyphs that requires it.

See Also

• textContainerForGlyphAtIndex
• textContainerOrigin (NSTextView)

usedRectForTextContainer

Returns the bounding rectangle for the glyphs laid out in aTextContainer, which tells “how full” it is.

public NSRect usedRectForTextContainer(NSTextContainer aTextContainer)

Discussion

This rectangle is given in the coordinate system of aTextContainer.

See Also

• containerSize (NSTextContainer)

usesScreenFonts

Returns true if the receiver calculates layout and displays text using screen fonts when possible, false otherwise.

public boolean usesScreenFonts()

See Also

• setUsesScreenFonts
• substituteFontForFont

Constants

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 GlyphAttributeInscribe. The only constants that the text system currently uses are GlyphInscribeBase (for most glyphs) and GlyphInscribeOverstrike (for nonbase glyphs). Nonbase glyphs occur when diacritical marks are applied to a base character, and the font does not have a single glyph to represent the combination. For example, if a font did not contain a single glyph for ü, but did contain separate glyphs for u and ¨, then it could be rendered with a base glyph u followed by a nonbase glyph ¨. In that case the nonbase glyph would have the value GlyphInscribeOverstrike for the inscribe attribute.

Glyph inscriptions are set during glyph generation.

The following constants are used by setTypesetterBehavior and typesetterBehavior to control the compatibility level of the typesetter.

Delegate Methods

layoutManagerDidCompleteLayoutForTextContainer

Informs the delegate that aLayoutManager has finished laying out text in aTextContainer.

public abstract void layoutManagerDidCompleteLayoutForTextContainer(NSLayoutManager aLayoutManager, NSTextContainer aTextContainer, boolean flag)

Discussion

aTextContainer is null if there aren’t enough containers to hold all the text; the delegate can use this information as a cue to add another container. If flag is true, aLayoutManager is finished laying out its text—this also means that aTextContainer is the final text container used by the layout manager. Delegates can use this information to show an indicator or background or to enable or disable a button that forces immediate layout of text.

layoutManagerDidInvalidateLayout

Informs the delegate that aLayoutManager has invalidated layout information (not glyph information).

public abstract void layoutManagerDidInvalidateLayout(NSLayoutManager aLayoutManager)

Discussion

This method is invoked only when layout was complete and then became invalidated for some reason. Delegates can use this information to show an indicator or background layout or to enable a button that forces immediate layout of text.

---