NSLayoutManager Class Reference for iOS

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 7.0 and later.
Declared in
NSLayoutManager.h

Overview

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 text view objects. In addition to its core function of laying out text, an NSLayoutManager object coordinates its text view objects, provides services to those text views to support 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.

NLayoutManager, NSTextStorage, and NSTextContainer can be accessed from subthreads as long as the app guarantees the access from a single thread.

Tasks

Text Storage

Text Containers

Delegate

Global Layout Manager Options

Invalidation of Layout and Glyphs

Causing Glyph Generation and Layout

Setting Glyphs and Glyph Properties

Getting Glyphs and Glyph Properties

Setting Layout Information

Getting Layout Information

Advanced Layout Queries

Supporting Drawing

Properties

allowsNonContiguousLayout

Indicates whether noncontiguous layout is enabled or disabled.

@property(nonatomic) BOOL allowsNonContiguousLayout
Discussion

If YES, then the layout manager may perform glyph generation and layout for a given portion of the text, without having glyphs or layout for preceding portions. The property allows, but does not require, the layout manager to use noncontiguous layout, and the layout manager may not do so, depending on its configuration. The default is NO.

Setting this property to YES significantly alters which portions of the text have glyph generation or layout performed when a given generation-causing method is invoked. It also gives significant performance benefits, especially for large documents.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

delegate

This layout manager’s delegate.

@property(assign, nonatomic) id<NSLayoutManagerDelegate> delegate
Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

extraLineFragmentRect

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

@property(readonly, nonatomic) CGRect extraLineFragmentRect
Discussion

The rectangle is defined in the coordinate system of its text container. NSZeroRect if there is no such rectangle.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

extraLineFragmentTextContainer

The text container that contains the extra line fragment rectangle. (read-only)

@property(readonly, nonatomic) NSTextContainer *extraLineFragmentTextContainer
Discussion

The value of this property is nil if there is no extra line fragment rectangle.

The extra line fragment is used for displaying the line at the end of a document when the last character in the document causes a line or paragraph break. Since the extra line is not associated with any glyph inside the layout manager, the information is handled separately from other line fragment rectangles. Typically the extra line fragment is placed in the last document content text container along with other normal line fragment rectangles.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

extraLineFragmentUsedRect

The rectangle enclosing the insertion point drawn in the extra line fragment rectangle. (read-only)

@property(readonly, nonatomic) CGRect extraLineFragmentUsedRect
Discussion

The rectangle is defined in the coordinate system of its text container. NSZeroRect if there is no extra line fragment rectangle.

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

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

hasNonContiguousLayout

Indicates whether the layout manager currently has any areas of noncontiguous layout. (read-only)

@property(readonly, nonatomic) BOOL hasNonContiguousLayout
Discussion

There may be times at which there is no noncontiguous layout, such as when layout is complete; this property enables the layout manager to report that to clients.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

hyphenationFactor

The current hyphenation threshold.

@property(nonatomic) CGFloat hyphenationFactor
Discussion

The hyphenation factor ranges 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.

Whenever (width of the real contents of the line) / (the line fragment width) is less than hyphenationFactor, hyphenation is attempted when laying out the line. Hyphenation slows down text layout and increases memory usage, so it should be used sparingly.

May be overridden on a per-paragraph basis by setting the NSParagraphStyle property hyphenationFactor.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

numberOfGlyphs

The number of glyphs in the receiver. (read-only)

@property(readonly, nonatomic) NSUInteger numberOfGlyphs
Discussion

If noncontiguous layout is not enabled, reading this property forces generation of glyphs for all characters.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

showsControlCharacters

Specifies whether to substitute visible glyphs for control characters in layout.

@property(nonatomic) BOOL showsControlCharacters
Discussion

If YES, the receiver substitutes visible glyphs for control characters if the font and script support it; if NO, it doesn’t. The default is NO.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

showsInvisibleCharacters

Specifies whether to substitute visible glyphs for whitespace and other typically invisible characters in layout.

@property(nonatomic) BOOL showsInvisibleCharacters
Discussion

If YES, the receiver substitutes visible glyphs for invisible characters if the font and script support it; if NO, it doesn’t. The default is NO.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

textContainers

The receiver’s text containers. (read-only)

@property(readonly, nonatomic) NSArray *textContainers
Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

textStorage

The receiver’s text storage object.

@property(assign, nonatomic) NSTextStorage *textStorage
Discussion

This property is set automatically when you add an NSLayoutManager to an NSTextStorage object; you should never need to set it directly.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

usesFontLeading

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

@property(nonatomic) BOOL usesFontLeading
Discussion

By default, a layout manager uses leading as specified by the font. However, this is not appropriate for most user-interface text, for which a fixed leading is usually specified by user-interface layout guidelines. This property enables the use of the font's leading to be turned off.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

Instance Methods

addTextContainer:

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

- (void)addTextContainer:(NSTextContainer *)container
Parameters
container

The text container to append.

Discussion

This method invalidates layout of all glyphs after the previous last container (that is, glyphs that were not previously laid out because they would not fit anywhere).

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

attachmentSizeForGlyphAtIndex:

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

- (CGSize)attachmentSizeForGlyphAtIndex:(NSUInteger)glyphIndex
Parameters
glyphIndex

The index of the attachment glyph.

Return Value

The size for the attachment cell to occupy. Returns {-1.0, -1.0} if there is no attachment laid for the specified glyph.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

boundingRectForGlyphRange:inTextContainer:

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

- (CGRect)boundingRectForGlyphRange:(NSRange)glyphRange inTextContainer:(NSTextContainer *)container
Parameters
glyphRange

The range of glyphs for which to return the bounding rectangle.

container

The text container in which the glyphs are laid out.

Return Value

The bounding rectangle enclosing the given range of glyphs.

Discussion

The range is intersected with the container's range before computing the bounding rectangle. This method can be used to translate glyph ranges into display rectangles for invalidation and redrawing when a range of glyphs changes. Bounding rectangles are always in container coordinates.

Performs glyph generation and layout if needed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

characterIndexForGlyphAtIndex:

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

- (NSUInteger)characterIndexForGlyphAtIndex:(NSUInteger)glyphIndex
Parameters
glyphIndex

The index of the glyph for which to return the associated character.

Return Value

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

Discussion

If noncontiguous layout is not enabled, this method causes generation of all glyphs up to and including glyphIndex. This method accepts an index beyond the last glyph, returning an index extrapolated from the last actual glyph index.

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

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

characterIndexForPoint:inTextContainer:fractionOfDistanceBetweenInsertionPoints:

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

- (NSUInteger)characterIndexForPoint:(CGPoint)point inTextContainer:(NSTextContainer *)container fractionOfDistanceBetweenInsertionPoints:(CGFloat *)partialFraction
Parameters
point

The point to test.

container

The text container within which the point is tested.

partialFraction

A fraction of the distance from the insertion point, logically before the given character to the next one.

Return Value

The index of the character falling under point.

Discussion

Analogous to glyphIndexForPoint:inTextContainer:fractionOfDistanceThroughGlyph:, but expressed in character index terms. The method returns the index of the character falling under point, expressed in coordinate system of container; if no character is under the point, the nearest character is returned, where nearest is defined according to the requirements of selection by mouse. However, this is not simply equivalent to taking the result of the corresponding glyph index method and converting it to a character index, because in some cases a single glyph represents more than one selectable character, for example an fi ligature glyph. In that case, there is an insertion point within the glyph, and this method returns one character or the other, depending on whether the specified point lies to the left or the right of that insertion point.

In general, this method returns only character indexes for which there is an insertion point. The partialFraction is a fraction of the distance from the insertion point, logically before the given character to the next one, which may be either to the right or to the left depending on directionality.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

characterRangeForGlyphRange:actualGlyphRange:

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

- (NSRange)characterRangeForGlyphRange:(NSRange)glyphRange actualGlyphRange:(NSRangePointer)actualGlyphRange
Parameters
glyphRange

The glyph range for which to return the character range.

actualGlyphRange

If not NULL, on output, points to the full range of glyphs generated by the character range returned. This range may be identical or slightly larger than the requested glyph range. For example, if the text storage contains the character “Ö” and the glyph cache contains the two atomic glyphs “O” and “¨”, and if glyphRange encloses only the first or second glyph, then actualGlyphRange is set to enclose both glyphs.

Return Value

The range of characters that generated the glyphs in glyphRange.

Discussion

If the length of glyphRange is 0, the resulting character range is a zero-length range just after the character(s) corresponding to the preceding glyph, and actualGlyphRange is also zero-length. If glyphRange extends beyond the text length, the method truncates the result to the number of characters in the text.

If noncontiguous layout is not enabled, this method forces the generation of glyphs for all characters up to and including the end of the returned range.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

drawBackgroundForGlyphRange:atPoint:

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

- (void)drawBackgroundForGlyphRange:(NSRange)glyphsToShow atPoint:(CGPoint)origin
Parameters
glyphsToShow

The range of glyphs for which the background is drawn.

origin

The position of the text container in the coordinate system of the currently focused view.

Discussion

This is a primitive method for drawing. You can override it to perform additional drawing, or to replace text drawing entirely, but not to change layout. You can call this method directly, but focus must already be locked on the destination view or image.

Background marks are such things as selection highlighting, text background color, and any background for marked text, along with block decoration such as table backgrounds and borders.

Performs glyph generation and layout if needed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

drawGlyphsForGlyphRange:atPoint:

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

- (void)drawGlyphsForGlyphRange:(NSRange)glyphsToShow atPoint:(CGPoint)origin
Parameters
glyphsToShow

The range of glyphs that are drawn.

origin

The position of the text container in the coordinate system of the currently focused view.

Discussion

This is a primitive method for drawing. You can override it to perform additional drawing, or to replace text drawing entirely, but not to change layout. You can call this method directly, but focus must already be locked on the destination view or image.

This method draws the actual glyphs, including attachments, as well as any underlines or strikethoughs.

Performs glyph generation and layout if needed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

drawsOutsideLineFragmentForGlyphAtIndex:

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

- (BOOL)drawsOutsideLineFragmentForGlyphAtIndex:(NSUInteger)glyphIndex
Parameters
glyphIndex

Index of the glyph.

Return Value

YES if the glyph at glyphIndex exceeds the bounds of the line fragment where it’s laid out; otherwise NO.

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.

This method causes glyph generation and layout for the line fragment containing the specified glyph, or if noncontiguous layout is not enabled, up to and including that line fragment.

Glyphs that draw outside their line fragment rectangles are considered by boundingRectForGlyphRange:inTextContainer:.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

drawStrikethroughForGlyphRange:strikethroughType:baselineOffset:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:

Draws a strikethrough for the glyphs in a given range.

- (void)drawStrikethroughForGlyphRange:(NSRange)glyphRange strikethroughType:(NSUnderlineStyle)strikethroughVal baselineOffset:(CGFloat)baselineOffset lineFragmentRect:(CGRect)lineRect lineFragmentGlyphRange:(NSRange)lineGlyphRange containerOrigin:(CGPoint)containerOrigin
Parameters
glyphRange

The range of glyphs for which to draw a strikethrough. The range must belong to a single line fragment rectangle (as returned by lineFragmentRectForGlyphAtIndex:effectiveRange:).

strikethroughVal

The style of strikethrough to draw. This value is a mask derived from the value for NSUnderlineStyleAttributeName—for example, (NSUnderlinePatternDash | NSUnderlineStyleThick). Subclasses can define custom strikethrough styles.

baselineOffset

Indicates how far above the text baseline the underline should be drawn.

lineRect

The line fragment rectangle containing the glyphs to draw strikethrough for.

lineGlyphRange

The range of all glyphs within lineRect.

containerOrigin

The origin of the line fragment rectangle’s NSTextContainer in its NSTextView.

Discussion

This method is invoked automatically by strikethroughGlyphRange:strikethroughType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:; you should rarely need to invoke it directly. This method’s strikethroughVal parameter does not take account of any setting forNSUnderlineByWordMask because that's taken care of by underlineGlyphRange:underlineType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

drawUnderlineForGlyphRange:underlineType:baselineOffset:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:

Draws underlining for the glyphs in a given range.

- (void)drawUnderlineForGlyphRange:(NSRange)glyphRange underlineType:(NSUnderlineStyle)underlineVal baselineOffset:(CGFloat)baselineOffset lineFragmentRect:(CGRect)lineRect lineFragmentGlyphRange:(NSRange)lineGlyphRange containerOrigin:(CGPoint)containerOrigin
Parameters
glyphRange

A range of glyphs, which must belong to a single line fragment rectangle (as returned by lineFragmentRectForGlyphAtIndex:effectiveRange:).

underlineVal

The style of underlining to draw. This value is a mask derived from the value for NSUnderlineStyleAttributeName—for example, (NSUnderlinePatternDash | NSUnderlineStyleThick). Subclasses can define custom underlining styles.

baselineOffset

Specifies the distance from the bottom of the bounding box of the specified glyphs in the specified range to their baseline.

lineRect

The line fragment rectangle containing the glyphs to draw underlining for.

lineGlyphRange

The range of all glyphs within lineRect.

containerOrigin

The origin of the NSTextContainer object containing lineRect, in text view coordinates.

Discussion

This method is invoked automatically by underlineGlyphRange:underlineType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:; you should rarely need to invoke it directly. This method’s underlineVal parameter does not take account of any setting forNSUnderlineByWordMask because that's taken care of by underlineGlyphRange:underlineType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:.

This method actually draws an appropriate underline for the glyph range given, whereas underlineGlyphRange:underlineType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin: potentially breaks the range it is given into subranges and calls this method for ranges that should actually have the underline drawn. In this way, the layout manager can avoid underlining the leading and trailing whitespace on a line. In addition, if the underlineType parameter indicates that only words—no whitespace—should be underlined, then underlineGlyphRange:underlineType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin: only passes word ranges to this method.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

ensureGlyphsForCharacterRange:

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

- (void)ensureGlyphsForCharacterRange:(NSRange)charRange
Parameters
charRange

The character range for which glyphs are generated.

Discussion

The layout manager reserves the right to perform glyph generation for larger ranges. If noncontiguous layout is disabled, then the affected range is always effectively extended to start at the beginning of the text.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

ensureGlyphsForGlyphRange:

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

- (void)ensureGlyphsForGlyphRange:(NSRange)glyphRange
Parameters
glyphRange

The glyph range for which glyphs are generated.

Discussion

The layout manager reserves the right to perform glyph generation for larger ranges. If noncontiguous layout is disabled, then the affected range is always effectively extended to start at the beginning of the text.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

ensureLayoutForBoundingRect:inTextContainer:

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

- (void)ensureLayoutForBoundingRect:(CGRect)bounds inTextContainer:(NSTextContainer *)container
Parameters
bounds

The area for which layout is performed.

container

The text container containing the area for which layout is performed.

Discussion

The layout manager reserves the right to perform layout for larger ranges. If noncontiguous layout is disabled, then the affected range is always effectively extended to start at the beginning of the text.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

ensureLayoutForCharacterRange:

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

- (void)ensureLayoutForCharacterRange:(NSRange)charRange
Parameters
charRange

The character range for which layout is performed.

Discussion

The layout manager reserves the right to perform layout for larger ranges. If noncontiguous layout is disabled, then the affected range is always effectively extended to start at the beginning of the text.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

ensureLayoutForGlyphRange:

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

- (void)ensureLayoutForGlyphRange:(NSRange)glyphRange
Parameters
glyphRange

The glyph range for which layout is performed.

Discussion

The layout manager reserves the right to perform layout for larger ranges. If noncontiguous layout is disabled, then the affected range is always effectively extended to start at the beginning of the text.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

ensureLayoutForTextContainer:

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

- (void)ensureLayoutForTextContainer:(NSTextContainer *)container
Parameters
container

The text container for which layout is performed.

Discussion

The layout manager reserves the right to perform layout for larger ranges. If noncontiguous layout is disabled, then the affected range is always effectively extended to start at the beginning of the text.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

enumerateEnclosingRectsForGlyphRange:withinSelectedGlyphRange:inTextContainer:usingBlock:

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

- (void)enumerateEnclosingRectsForGlyphRange:(NSRange)glyphRange withinSelectedGlyphRange:(NSRange)selectedRange inTextContainer:(NSTextContainer *)textContainer usingBlock:(void (^)(CGRect rect, BOOL *stop))block
Parameters
glyphRange

The glyph range for which to return enclosing rectangles.

selectedRange

Selected glyphs within glyphRange, which can affect the size of the rectangles. If not interested in selection rectangles, pass {NSNotFound, 0} as the selected range.

textContainer

The text container in which the glyphs are laid out.

block

The block to apply to the glyph range. The block has two arguments:

rect

The current enclosing rectangle.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only set this Boolean to YES within the block.

Discussion

These rectangles are always in container coordinates. They can be used to draw the text background or highlight for the given range of characters. The rectangles don’t necessarily enclose glyphs that draw outside their line fragment rectangles; use boundingRectForGlyphRange:inTextContainer: to determine the area that contains all drawing performed for a range of glyphs.

If a selected range is given in the second argument, the rectangles returned are correct for drawing the selection. Selection rectangles are generally more complicated than enclosing rectangles, and supplying a selected range determines whether the method does this extra work. This method does the minimum amount of work required to answer the question.

Performs glyph generation and layout if needed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

enumerateLineFragmentsForGlyphRange:usingBlock:

Enumerates line fragments intersecting with the given glyph range.

- (void)enumerateLineFragmentsForGlyphRange:(NSRange)glyphRange usingBlock:(void (^)(CGRect rect, CGRect usedRect, NSTextContainer *textContainer, NSRange glyphRange, BOOL *stop))block
Parameters
glyphRange

The glyph range for which to return line fragment rectangles.

block

The block to apply to the glyph range. The block has five arguments:

rect

The current line fragment rectangle.

usedRect

The portion of the line fragment rectangle that actually contains glyphs or other marks that are drawn (including the text container’s line fragment padding).

textContainer

The text container in which the glyphs are laid out.

glyphRange

The range of glyphs laid out in the current line fragment.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only set this Boolean to YES within the block.

Discussion

This method causes glyph generation and layout for the line fragment containing the glyphs in the specified range, or if noncontiguous layout is not enabled, for all of the text up to and including that line fragment.

Line fragment rectangles are always in container coordinates.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

fillBackgroundRectArray:count:forCharacterRange:color:

Fills background rectangles with a color.

- (void)fillBackgroundRectArray:(const CGRect *)rectArray count:(NSUInteger)rectCount forCharacterRange:(NSRange)charRange color:(UIColor *)color
Parameters
rectArray

The array of rectangles to fill.

rectCount

The number of rectangles in rectArray.

charRange

The range of characters whose background rectangles are filled.

color

The fill color.

Discussion

This is the primitive method used by drawBackgroundForGlyphRange:atPoint:, providing a finer-grained override point for actually filling rectangles with a particular background color for a background color attribute, a selected or marked range highlight, a block decoration, or any other rectangle fill needed by that method. As with showCGGlyphs:positions:count:font:matrix:attributes:inContext:, the character range and color are merely for informational purposes; the color will already be set in the graphics state. If for any reason you modify it, you must restore it before returning from this method.

This method operates in terms of character ranges, because the relevant attributes are expressed on characters, and they don't always lie on glyph boundaries—for example, when one character of an “fi” ligature is highlighted.

You should never call this method, but you might override it. The default implementation simply fills the rectangles in the specified array. Applications can control the operation used, or modify the drawing, by overriding this method in an NSLayoutManager subclass.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

firstUnlaidCharacterIndex

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

- (NSUInteger)firstUnlaidCharacterIndex
Return Value

The character index.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

firstUnlaidGlyphIndex

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

- (NSUInteger)firstUnlaidGlyphIndex
Return Value

The glyph index.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

fractionOfDistanceThroughGlyphForPoint:inTextContainer:

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

- (CGFloat)fractionOfDistanceThroughGlyphForPoint:(CGPoint)point inTextContainer:(NSTextContainer *)container
Parameters
point

The point for which to return the fractional distance through the underlying glyph, in container coordinates.

container

The container in which the glyph is laid out.

Return Value

The fraction of the distance, through the underlying glyph, of point.

Discussion

If the glyph stream contains the glyphs “A” and “b”, with the width of “A” being 13 points, and the user clicks at a location 8 points into “A”, the fraction of distance is 8/13, or 0.615. If the nearest glyph doesn’t lie under point at all (for example, if point is beyond the beginning or end of a line), this fraction of distance is 0 or 1.

You should always call the main method, not the primitives, but you may override this primitive method.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

getFirstUnlaidCharacterIndex:glyphIndex:

Returns the index for the first character or glyph, or both, having invalid layout information.

- (void)getFirstUnlaidCharacterIndex:(NSUInteger *)charIndex glyphIndex:(NSUInteger *)glyphIndex
Parameters
charIndex

If not NULL, on return, the index of the first character that has invalid layout information

glyphIndex

If not NULL, on return, the index of the first glyph that has invalid layout information.

Discussion

Either parameter may be NULL, in which case the receiver simply ignores it.

As part of its implementation, this method calls firstUnlaidCharacterIndex and firstUnlaidGlyphIndex. To change this method’s behavior, override those two methods instead of this one.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

getGlyphsInRange:glyphs:properties:characterIndexes:bidiLevels:

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

- (NSUInteger)getGlyphsInRange:(NSRange)glyphRange glyphs:(CGGlyph *)glyphBuffer properties:(NSGlyphProperty *)props characterIndexes:(NSUInteger *)charIndexBuffer bidiLevels:(unsigned char *)bidiLevelBuffer
Parameters
glyphRange

The range of glyphs to fill in.

glyphBuffer

On output, the sequence of glyphs in the given glyph range.

props

If not NULL, on output, the glyph properties corresponding to the filled-in glyphs.

charIndexBuffer

If not NULL, on output, the indexes of the original characters corresponding to the given glyph range. Note that a glyph at index 1 is not necessarily mapped to the character at index 1, since a glyph may be for a ligature or accent.

bidiLevelBuffer

If not NULL, on output, the direction of each glyph for bidirectional text. The values range from 0 to 61 as defined by Unicode Standard Annex #9. An even value means the glyph goes left-to-right, and an odd value means the glyph goes right-to-left.

Return Value

The number of glyphs returned in glyphBuffer.

Discussion

Each pointer passed in should either be NULL or else point to sufficient memory to hold glyphRange.length elements.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

getLineFragmentInsertionPointsForCharacterAtIndex:alternatePositions:inDisplayOrder:positions:characterIndexes:

Returns insertion points in bulk for a given line fragment.

- (NSUInteger)getLineFragmentInsertionPointsForCharacterAtIndex:(NSUInteger)charIndex alternatePositions:(BOOL)aFlag inDisplayOrder:(BOOL)dFlag positions:(CGFloat *)positions characterIndexes:(NSUInteger *)charIndexes
Parameters
charIndex

The character index of one character within the line fragment.

aFlag

If YES, returns alternate, rather than primary, insertion points.

dFlag

If YES, returns insertion points in display, rather than logical, order.

positions

On output, the positions of the insertion points, in the order specified.

charIndexes

On output, the indexes of the characters corresponding to the returned insertion points.

Return Value

The number of insertion points returned.

Discussion

The method allows clients to obtain all insertion points for a line fragment in one call. Each pointer passed in should either be NULL or else point to sufficient memory to hold as many elements as there are insertion points in the line fragment (which cannot be more than the number of characters + 1). The returned positions indicate a transverse offset relative to the line fragment rectangle's origin. Internal caching is used to ensure that repeated calls to this method for the same line fragment (possibly with differing values for other arguments) are not significantly more expensive than a single call.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

glyphAtIndex:

Returns the glyph at the given glyph index.

- (CGGlyph)glyphAtIndex:(NSUInteger)glyphIndex
Parameters
glyphIndex

The index of a glyph in the receiver. This value must not exceed the bounds of the receiver’s glyph array.

Return Value

The glyph at glyphIndex.

Discussion

Raises an NSRangeException 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. Another method, glyphAtIndex:isValidIndex:, generates glyphs only up to the one requested, so using it can be more efficient.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

glyphAtIndex:isValidIndex:

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

- (CGGlyph)glyphAtIndex:(NSUInteger)glyphIndex isValidIndex:(BOOL *)isValidIndex
Parameters
glyphIndex

The index of the glyph to be returned.

isValidIndex

If not NULL, on output, YES if the requested index is in range; otherwise NO.

Return Value

The glyph at the requested index, or NSNullGlyph if the requested index is out of the range {0, numberOfGlyphs}.

Discussion

If noncontiguous layout is not enabled, this method causes generation of all glyphs up to and including glyphIndex.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

glyphIndexForCharacterAtIndex:

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

- (NSUInteger)glyphIndexForCharacterAtIndex:(NSUInteger)charIndex
Parameters
charIndex

The index of the character for which to return the associated glyph.

Return Value

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

Discussion

If noncontiguous layout is not enabled, this method causes generation of all glyphs up to and including those associated with the specified character. This method accepts an index beyond the last character, returning an index extrapolated from the last actual character index.

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

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

glyphIndexForPoint:inTextContainer:

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

- (NSUInteger)glyphIndexForPoint:(CGPoint)point inTextContainer:(NSTextContainer *)container
Parameters
point

The point for which to return the glyph, in coordinates of container.

container

The container in which the returned glyph is laid out.

Return Value

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

Discussion

You should always call the main method, not the primitive, but you might override this primitive method.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

glyphIndexForPoint:inTextContainer:fractionOfDistanceThroughGlyph:

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

- (NSUInteger)glyphIndexForPoint:(CGPoint)point inTextContainer:(NSTextContainer *)container fractionOfDistanceThroughGlyph:(CGFloat *)partialFraction
Parameters
point

The point for which to return the glyph, in coordinates of container.

container

The container in which the returned glyph is laid out.

partialFraction

If not NULL, on output, the fraction of the distance between the location of the glyph returned and the location of the next glyph.

Return Value

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

Discussion

If no glyph is under point, the nearest glyph is returned, where nearest is defined according to the requirements of selection by mouse. Clients who wish to determine whether the the point actually lies within the bounds of the glyph returned should follow this with a call to boundingRectForGlyphRange:inTextContainer: and test whether the point falls in the rectangle returned by that method. If partialFraction is non-NULL, it returns by reference the fraction of the distance between the location of the glyph returned and the location of the next glyph.

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

If the glyph stream contains the glyphs “A” and “b”, with the width of “A” being 13 points, and the user clicks at a location 8 points into “A”, partialFraction 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.

As part of its implementation, this method calls fractionOfDistanceThroughGlyphForPoint:inTextContainer: and glyphIndexForPoint:inTextContainer:. To change this method’s behavior, override those two methods instead of this one.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

glyphRangeForBoundingRect:inTextContainer:

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

- (NSRange)glyphRangeForBoundingRect:(CGRect)bounds inTextContainer:(NSTextContainer *)container
Parameters
bounds

The bounding rectangle for which to return glyphs.

container

The text container in which the glyphs are laid out.

Return Value

The range of glyphs that would need to be displayed in order to draw all glyphs that fall (even partially) within the given bounding rectangle. The range returned can include glyphs that don’t fall inside or intersect bounds, although the first and last glyphs in the range always do. At most this method returns the glyph range for the whole container.

Discussion

This method is used to determine which glyphs need to be displayed within a given rectangle.

Performs glyph generation and layout if needed. Bounding rectangles are always in container coordinates.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

glyphRangeForBoundingRectWithoutAdditionalLayout:inTextContainer:

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

- (NSRange)glyphRangeForBoundingRectWithoutAdditionalLayout:(CGRect)bounds inTextContainer:(NSTextContainer *)container
Parameters
bounds

The bounding rectangle for which to return glyphs.

container

The text container in which the glyphs are laid out.

Return Value

The range of glyphs that would need to be displayed in order to draw all glyphs that fall (even partially) within the given bounding rectangle. The range returned can include glyphs that don’t fall inside or intersect bounds, although the first and last glyphs in the range always do. At most this method returns the glyph range for the whole container.

Discussion

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

Bounding rectangles are always in container coordinates.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

glyphRangeForCharacterRange:actualCharacterRange:

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

- (NSRange)glyphRangeForCharacterRange:(NSRange)charRange actualCharacterRange:(NSRangePointer)actualCharRange
Parameters
charRange

The character range for which to return the generated glyph range.

actualCharRange

If not NULL, on output, points to the actual range of characters that fully define the glyph range returned. This range may be identical to or slightly larger than the requested character range. For example, if the text storage contains the characters "O" and "¨“, and the glyph store contains the single precomposed glyph "¨Ö”, and if charRange encloses only the first or second character, then actualCharRange is set to enclose both characters.

Return Value

The range of glyphs generated by charRange.

Discussion

If the length of charRange is 0, the resulting glyph range is a zero-length range just after the glyph(s) corresponding to the preceding character, and actualCharRange will also be zero-length. If charRange extends beyond the text length, the method truncates the result to the number of glyphs in the text.

If noncontiguous layout is not enabled, this method forces the generation of glyphs for all characters up to and including the end of the specified range.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

glyphRangeForTextContainer:

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

- (NSRange)glyphRangeForTextContainer:(NSTextContainer *)container
Parameters
container

The text container in which the glyphs are laid out.

Return Value

The range of glyphs laid out in the given text container.

Discussion

This is a less efficient method than the similar textContainerForGlyphAtIndex:effectiveRange:.

Performs glyph generation and layout if needed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

insertTextContainer:atIndex:

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

- (void)insertTextContainer:(NSTextContainer *)container atIndex:(NSUInteger)index
Parameters
container

The text container to insert.

index

The index in the series of text containers at which to insert aTextContainer.

Discussion

This method invalidates layout for all subsequent NSTextContainer objects, and invalidates glyph information as needed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

invalidateDisplayForCharacterRange:

Invalidates display for the given character range.

- (void)invalidateDisplayForCharacterRange:(NSRange)charRange
Parameters
charRange

The character range for which display is invalidated.

Discussion

Parts of the range that are not laid out are remembered and redisplayed later when the layout is available. Does not actually cause layout.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

invalidateDisplayForGlyphRange:

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

- (void)invalidateDisplayForGlyphRange:(NSRange)glyphRange
Parameters
glyphRange

The range of glyphs to invalidate.

Discussion

You should rarely need to invoke this method.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

invalidateGlyphsForCharacterRange:changeInLength:actualCharacterRange:

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

- (void)invalidateGlyphsForCharacterRange:(NSRange)charRange changeInLength:(NSInteger)delta actualCharacterRange:(NSRangePointer)actualCharRange
Parameters
charRange

The range of characters for which to invalidate glyphs.

delta

The number of characters added or removed.

actualCharRange

If not NULL, on output, the actual range invalidated after any necessary expansion. This range can be larger than the range of characters given due to the effect of context on glyphs and layout.

Discussion

This method 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:actualCharacterRange:, passing charRange as the first argument.

This method is used by the layout mechanism and should be invoked only during typesetting, in almost all cases only by the layout manager. For example, a custom layout manager might invoke it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

invalidateLayoutForCharacterRange:actualCharacterRange:

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

- (void)invalidateLayoutForCharacterRange:(NSRange)charRange actualCharacterRange:(NSRangePointer)actualCharRange
Parameters
charRange

The range of characters to invalidate.

actualCharRange

If not NULL, on output, the actual range invalidated after any necessary expansion.

Discussion

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

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

isValidGlyphIndex:

Indicates whether the specified index refers to a valid glyph.

- (BOOL)isValidGlyphIndex:(NSUInteger)glyphIndex
Parameters
glyphIndex

The index of a glyph in the receiver.

Return Value

YES if the specified glyphIndex refers to a valid glyph, otherwise NO.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

lineFragmentRectForGlyphAtIndex:effectiveRange:

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

- (CGRect)lineFragmentRectForGlyphAtIndex:(NSUInteger)glyphIndex effectiveRange:(NSRangePointer)effectiveGlyphRange
Parameters
glyphIndex

The glyph for which to return the line fragment rectangle.

effectiveGlyphRange

If not NULL, on output, the range for all glyphs in the line fragment.

Return Value

The line fragment in which the given glyph is laid out.

Discussion

This method causes glyph generation and layout for the line fragment containing the specified glyph, or if noncontiguous layout is not enabled, for all of the text up to and including that line fragment.

Line fragment rectangles are always in container coordinates.

Overriding this method is not recommended. If the the line fragment rectangle needs to be modified, that should be done by calling setLineFragmentRect:forGlyphRange:usedRect:.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

lineFragmentUsedRectForGlyphAtIndex:effectiveRange:

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

- (CGRect)lineFragmentUsedRectForGlyphAtIndex:(NSUInteger)glyphIndex effectiveRange:(NSRangePointer)effectiveGlyphRange
Parameters
glyphIndex

The glyph for which to return the line fragment used rectangle.

effectiveGlyphRange

If not NULL, on output, the range for all glyphs in the line fragment.

Return Value

The used rectangle for the line fragment in which the given glyph is laid out.

Discussion

This method causes glyph generation and layout for the line fragment containing the specified glyph, or if noncontiguous layout is not enabled, up to and including that line fragment.

Line fragment used rectangles are always in container coordinates.

Overriding this method is not recommended. If the the line fragment used rectangle needs to be modified, that should be done by calling setLineFragmentRect:forGlyphRange:usedRect:.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

locationForGlyphAtIndex:

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

- (CGPoint)locationForGlyphAtIndex:(NSUInteger)glyphIndex
Parameters
glyphIndex

The glyph whose location is returned.

Return Value

The location of the given glyph.

Discussion

If the given glyph does not have an explicit location set for it (for example, if it is part of—but not first in—a sequence of nominally spaced characters), the location is calculated by glyph advancements from the location of the most recent preceding glyph with a location set.

Glyph locations are relative to their line fragment rectangle's origin. The line fragment rectangle in turn is defined in the coordinate system of the text container where it resides.

This method causes glyph generation and layout for the line fragment containing the specified glyph, or if noncontiguous layout is not enabled, up to and including that line fragment.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

notShownAttributeForGlyphAtIndex:

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

- (BOOL)notShownAttributeForGlyphAtIndex:(NSUInteger)glyphIndex
Parameters
glyphIndex

Index of the glyph.

Return Value

YES if the glyph at glyphIndex is not shown; otherwise NO.

Discussion

Some glyphs are not shown. For example, a tab, newline, or attachment glyph is not 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, although they leave no visible marks.

This method causes glyph generation and layout for the line fragment containing the specified glyph, or if noncontiguous layout is not enabled, up to and including that line fragment.

Raises an NSRangeException if glyphIndex is out of bounds.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

processEditingForTextStorage:edited:range:changeInLength:invalidatedRange:

Sent from the NSTextStorage method processEditing to notify the layout manager of an edit action.

- (void)processEditingForTextStorage:(NSTextStorage *)textStorage edited:(NSTextStorageEditActions)editMask range:(NSRange)newCharRange changeInLength:(NSInteger)delta invalidatedRange:(NSRange)invalidatedCharRange
Parameters
textStorage

The text storage object processing edits.

editMask

The types of edits done: NSTextStorageEditedAttributes, NSTextStorageEditedCharacters, or both.

newCharRange

The range in the final string that was explicitly edited.

delta

The length delta for the editing changes.

invalidatedCharRange

The range of characters that changed as a result of attribute fixing. This invalidated range is either equal to newCharRange or larger.

Discussion

Layout managers must not change the contents of the text storage during the execution of this message.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

propertyForGlyphAtIndex:

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

- (NSGlyphProperty)propertyForGlyphAtIndex:(NSUInteger)glyphIndex
Parameters
glyphIndex

The glyph whose glyph property is returned.

Return Value

The glyph property associated with the specified glyph. “NSGlyphProperty” lists the values that can be returned.

Discussion

If noncontiguous layout is not enabled, this method causes generation of all glyphs up to and including the one at glyphIndex.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

rangeOfNominallySpacedGlyphsContainingIndex:

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

- (NSRange)rangeOfNominallySpacedGlyphsContainingIndex:(NSUInteger)glyphIndex
Parameters
glyphIndex

Index of the glyph to test.

Return Value

The range of nominally spaced glyphs.

Discussion

The range returned begins with the first glyph, counting back from glyphIndex, that has a location set, and it continues up to, but does not include, the next glyph that has a location set.

Performs glyph generation and layout if needed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

removeTextContainerAtIndex:

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

- (void)removeTextContainerAtIndex:(NSUInteger)index
Parameters
index

The index of the text container to remove.

Discussion

This method invalidates glyph information as needed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

setAttachmentSize:forGlyphRange:

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

- (void)setAttachmentSize:(CGSize)attachmentSize forGlyphRange:(NSRange)glyphRange
Parameters
attachmentSize

The glyph size to set.

glyphRange

The attachment glyph’s position in the glyph stream.

Discussion

For a glyph corresponding to an attachment, this method should be called to set the size for the attachment cell to occupy. The glyph's value should be NSControlGlyph.

This method is used by the layout mechanism and should be invoked only during typesetting, in almost all cases only by the layout manager. For example, a custom layout manager might invoke it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

setDrawsOutsideLineFragment:forGlyphAtIndex:

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

- (void)setDrawsOutsideLineFragment:(BOOL)flag forGlyphAtIndex:(NSUInteger)glyphIndex
Parameters
flag

If YES, sets the given glyph to draw outside its line fragment; if NO, the glyph does not draw outside.

glyphIndex

Index of the glyph to set.

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 information is important for determining whether additional lines need to be redrawn as a result of changes to any given line fragment.

This method is used by the layout mechanism and should be invoked only during typesetting, in almost all cases only by the layout manager. For example, a custom layout manager might invoke it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

setExtraLineFragmentRect:usedRect:textContainer:

Sets the bounds and container for the extra line fragment.

- (void)setExtraLineFragmentRect:(CGRect)fragmentRect usedRect:(CGRect)usedRect textContainer:(NSTextContainer *)container
Parameters
fragmentRect

The rectangle to set.

usedRect

Indicates where the insertion point is drawn.

container

The text container where the rectangle is to be laid out.

Discussion

The extra line fragment is used when the text backing ends with a hard line break or when the text backing is totally empty, to define the extra line which needs to be displayed at the end of the text. If the text backing is not empty and does not end with a hard line break, this should be set to NSZeroRect and nil.

Line fragment rectangles and line fragment used rectangles are always in container coordinates.

This method is used by the layout mechanism and should be invoked only during typesetting, in almost all cases only by the layout manager. For example, a custom layout manager might invoke it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

setGlyphs:properties:characterIndexes:font:forGlyphRange:

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

- (void)setGlyphs:(const CGGlyph *)glyphs properties:(const NSGlyphProperty *)props characterIndexes:(const NSUInteger *)charIndexes font:(UIFont *)aFont forGlyphRange:(NSRange)glyphRange
Parameters
glyphs

A pointer to the layout manager's glyph cache.

props

A pointer to a buffer containing glyph properties for the glyphs in the cache.

charIndexes

A pointer to the starting index for the characters in the text storage for which glyphs are generated.

aFont

A font to override the font attributes in the text storage for the specified character range.

glyphRange

The range of glyphs in the glyph cache to set.

Discussion

This method is invoked by text system during the glyph generation process. The only place apps are allowed to call this method directly is from an implementation of the NSLayoutManagerDelegate protocol method layoutManager:shouldGenerateGlyphs:properties:characterIndexes:font:forGlyphRange:.

Each array has glyphRange.length items. The specified charIndexes must be contiguous (no skipped indexes), enabling multiple items to have a same character index (as when one character index generates multiple glyph IDs). Due to font substitution, aFont passed into this method might not match the font in the attributes dictionary. Calling this method for a character range that has previously calculated layout information invalidates the layout and display.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

setLineFragmentRect:forGlyphRange:usedRect:

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

- (void)setLineFragmentRect:(CGRect)fragmentRect forGlyphRange:(NSRange)glyphRange usedRect:(CGRect)usedRect
Parameters
fragmentRect

The rectangle of the line fragment.

glyphRange

The range of glyphs to be associated with fragmentRect.

usedRect

The portion of fragmentRect that actually contains glyphs or other marks that are drawn (including the text container’s line fragment padding. Must be equal to or contained within fragmentRect.

Discussion

The layout manager must specify the text container first with setTextContainer:forGlyphRange:, and it sets the exact positions of the glyphs afterwards with setLocation:forStartOfGlyphRange:.

In the course of layout, all glyphs should end up being included in a range passed to this method, but only glyphs that start a new line fragment should be at the start of such ranges.

Line fragment rectangles and line fragment used rectangles are always in container coordinates.

This method is used by the layout mechanism and should be invoked only during typesetting, in almost all cases only by the layout manager. For example, a custom layout manager might invoke it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

setLocation:forStartOfGlyphRange:

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

- (void)setLocation:(CGPoint)location forStartOfGlyphRange:(NSRange)glyphRange
Parameters
location

The location to which the first glyph is set, relative to the origin of the glyph’s line fragment origin.

glyphRange

The glyphs whose location is set.

Discussion

Setting the location for a glyph range implies that its first glyph is not nominally spaced with respect to the previous glyph. In the course of layout, all glyphs should end up being included in a range passed to this method, but only glyphs that start a new nominal range should be at the start of such ranges. The first glyph in a line fragment should always start a new nominal range. Glyph locations are given relative to their line fragment rectangle's origin.

Before setting the location for a glyph range, you must specify the text container with setTextContainer:forGlyphRange: and the line fragment rectangle with setLineFragmentRect:forGlyphRange:usedRect:.

This method is used by the layout mechanism and should be invoked only during typesetting, in almost all cases only by the layout manager. For example, a custom layout manager might invoke it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

setNotShownAttribute:forGlyphAtIndex:

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

- (void)setNotShownAttribute:(BOOL)flag forGlyphAtIndex:(NSUInteger)glyphIndex
Parameters
flag

If YES, the glyph is not shown; if NO, it is shown.

glyphIndex

Index of the glyph whose attribute is set.

Discussion

The layout manager decides which glyphs are not shown and sets this attribute to ensure that those glyphs are not displayed. For example, a tab or newline character doesn’t leave any marks; it just indicates where following glyphs are laid out.

Raises an NSRangeException if glyphIndex is out of bounds.

This method is used by the layout mechanism and should be invoked only during typesetting, in almost all cases only by the layout manager. For example, a custom layout manager might invoke it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

setTextContainer:forGlyphRange:

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

- (void)setTextContainer:(NSTextContainer *)container forGlyphRange:(NSRange)glyphRange
Parameters
container

The text container to set.

glyphRange

The range of glyphs to lay out.

Discussion

The layout within the container is specified with the setLineFragmentRect:forGlyphRange:usedRect: and setLocation:forStartOfGlyphRange: methods.

This method is used by the layout mechanism and should be invoked only during typesetting, in almost all cases only by the layout manager. For example, a custom layout manager might invoke it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

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

Renders the glyphs at the specified positions and attributes into the given graphics context.

- (void)showCGGlyphs:(const CGGlyph *)glyphs positions:(const CGPoint *)positions count:(NSUInteger)glyphCount font:(UIFont *)font matrix:(CGAffineTransform)textMatrix attributes:(NSDictionary *)attributes inContext:(CGContextRef)graphicsContext
Parameters
glyphs

The glyphs to draw; may contain embedded NULL bytes.

positions

The positions at which to draw the glyphs. In the user space coordinate system.

glyphCount

The number of glyphs.

font

The font applied to the graphics state. This value can be different from the NSFontAttributeName value in the attributes argument because of various font substitutions that the system automatically executes.

textMatrix

The affine transform mapping the text space coordinate system to the user space coordinate system. The tx and ty components of textMatrix are ignored since Quartz overrides them with the glyph positions.

attributes

A dictionary of glyph attributes.

graphicsContext

If non-nil, graphicsContext is already configured according to the text attributes arguments: font, textMatrix, and attributes.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

strikethroughGlyphRange:strikethroughType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:

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

- (void)strikethroughGlyphRange:(NSRange)glyphRange strikethroughType:(NSUnderlineStyle)strikethroughVal lineFragmentRect:(CGRect)lineRect lineFragmentGlyphRange:(NSRange)lineGlyphRange containerOrigin:(CGPoint)containerOrigin
Parameters
glyphRange

The range of glyphs for which to draw a strikethrough. The range must belong to a single line fragment rectangle (as returned by lineFragmentRectForGlyphAtIndex:effectiveRange:).

strikethroughVal

The style of underlining to draw. This value is a mask derived from the value for NSUnderlineStyleAttributeName—for example, (NSUnderlinePatternDash | NSUnderlineStyleThick | NSUnderlineByWordMask). Subclasses can define custom underlining styles.

lineRect

The line fragment rectangle containing the glyphs to draw strikethrough for.

lineGlyphRange

The range of all glyphs within lineRect.

containerOrigin

The origin of the line fragment rectangle’s NSTextContainer in its NSTextView.

Discussion

This method determines which glyphs actually need to have a strikethrough drawn based on strikethroughVal. After determining which glyphs to draw strikethrough on, this method invokes drawStrikethroughForGlyphRange:strikethroughType:baselineOffset:lineFragmentRect:lineFragmentGlyphRange:containerOrigin: for each contiguous range of glyphs that requires it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

textContainerChangedGeometry:

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

- (void)textContainerChangedGeometry:(NSTextContainer *)container
Parameters
container

The text container whose layout is invalidated.

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 or shape changes (a text container that dynamically adjusts its properties to wrap text around placed graphics, for example, must do so when a graphic is added, moved, or removed).

Invalidates layout of all glyphs in container and all subsequent containers.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

textContainerForGlyphAtIndex:effectiveRange:

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

- (NSTextContainer *)textContainerForGlyphAtIndex:(NSUInteger)glyphIndex effectiveRange:(NSRangePointer)effectiveGlyphRange
Parameters
glyphIndex

Index of a glyph in the returned container.

effectiveGlyphRange

If not NULL, on output, points to the whole range of glyphs that are in the returned container.

Return Value

The text container in which the glyph at glyphIndex is laid out.

Discussion

This method causes glyph generation and layout for the line fragment containing the specified glyph, or if noncontiguous layout is not enabled, up to and including that line fragment. If noncontiguous layout is not enabled and effectiveGlyphRange is not NULL, this method additionally causes glyph generation and layout for the entire text container containing the specified glyph.

Overriding this method is not recommended.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

truncatedGlyphRangeInLineFragmentForGlyphAtIndex:

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

- (NSRange)truncatedGlyphRangeInLineFragmentForGlyphAtIndex:(NSUInteger)glyphIndex
Parameters
glyphIndex

A glyph whose line fragment is tested.

Return Value

The range of truncated glyphs for a line fragment containing the specified glyph, or, when there is no truncation for the line fragment, {NSNotFound, 0}.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

underlineGlyphRange:underlineType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:

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

- (void)underlineGlyphRange:(NSRange)glyphRange underlineType:(NSUnderlineStyle)underlineVal lineFragmentRect:(CGRect)lineRect lineFragmentGlyphRange:(NSRange)lineGlyphRange containerOrigin:(CGPoint)containerOrigin
Parameters
glyphRange

A range of glyphs, which must belong to a single line fragment rectangle (as returned by lineFragmentRectForGlyphAtIndex:effectiveRange:).

underlineVal

The style of underlining to draw. This value is a mask derived from the value for NSUnderlineStyleAttributeName, for example, (NSUnderlinePatternDash | NSUnderlineStyleThick | NSUnderlineByWordMask). Subclasses can define custom underlining styles.

lineRect

The line fragment rectangle containing the glyphs to draw underlining for.

lineGlyphRange

The range of all glyphs within that line fragment rectangle.

containerOrigin

The origin of the line fragment rectangle’s NSTextContainer, in text view coordinates.

Discussion

This method determines which glyphs actually need to be underlined based on underlineVal. With NSUnderlineStyleSingle, for example, leading and trailing whitespace isn’t underlined, but whitespace between visible glyphs is. The NSUnderlineByWord style omits underlining on any whitespace. After determining which glyphs to draw underlining on, this method invokes drawUnderlineForGlyphRange:underlineType:baselineOffset:lineFragmentRect:lineFragmentGlyphRange:containerOrigin: for each contiguous range of glyphs that requires it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

usedRectForTextContainer:

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

- (CGRect)usedRectForTextContainer:(NSTextContainer *)container
Parameters
container

The text container in which the glyphs are laid out.

Return Value

The bounding rectangle of the glyphs in container.

Discussion

The returned bounding rectangle represents the text container's currently used area, that is, the size that the view would need to be in order to display all the glyphs that are currently laid out in the container.

This method causes neither glyph generation nor layout. Used rectangles are always in container coordinates.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSLayoutManager.h

Constants

NSTextLayoutOrientation

Describes the text layout orientation.

enum {
   NSTextLayoutOrientationHorizontal = 0,
   NSTextLayoutOrientationVertical = 1,
};
typedef NSInteger NSTextLayoutOrientation;
Constants
NSTextLayoutOrientationHorizontal

Lines rendered horizontally, extending from top to bottom

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSTextLayoutOrientationVertical

Lines rendered vertically, extending from right to left

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSGlyphProperty

Describes glyph properties.

enum {
   NSGlyphPropertyNull = (1 << 0),
   NSGlyphPropertyControlCharacter = (1 << 1),
   NSGlyphPropertyElastic = (1 << 2),
   NSGlyphPropertyNonBaseCharacter = (1 << 3)
};
typedef NSInteger NSGlyphProperty;
Constants
NSGlyphPropertyNull

Null glyph ignored for layout and display.

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSGlyphPropertyControlCharacter

Control character such as tab, attachment, and so on, that has associated special behavior.

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSGlyphPropertyElastic

Glyphs with elastic glyph width behavior such as whitespace.

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSGlyphPropertyNonBaseCharacter

Glyphs with combining properties, typically characters in Unicode Mn class.

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSControlCharacterAction

Describes actions control characters can cause.

{
   NSControlCharacterZeroAdvancementAction = (1 << 0),
   NSControlCharacterWhitespaceAction = (1 << 1),
   NSControlCharacterHorizontalTabAction = (1 << 2),
   NSControlCharacterLineBreakAction = (1 << 3),
   NSControlCharacterParagraphBreakAction = (1 << 4),
   NSControlCharacterContainerBreakAction = (1 << 5)
};
typedef NSInteger NSControlCharacterAction;
Constants
NSControlCharacterZeroAdvancementAction

Glyphs with this action are filtered out from layout (notShownAttributeForGlyphAtIndex: == YES for the glyph).

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSControlCharacterWhitespaceAction

The width for a glyph with this action is determined by the delegate method layoutManager:boundingBoxForControlGlyphAtIndex:forTextContainer:proposedLineFragment:glyphPosition:characterIndex: if the method is implemented; otherwise, same as NSControlCharacterZeroAdvancementAction.

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSControlCharacterHorizontalTabAction

Treated as a tab character.

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSControlCharacterLineBreakAction

Causes a line break.

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSControlCharacterParagraphBreakAction

Causes a paragraph break; firstLineHeadIndent is used for the following glyph.

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

NSControlCharacterContainerBreakAction

Causes container break.

Available in iOS 7.0 and later.

Declared in NSLayoutManager.h.

Discussion

These constants are used by the layoutManager:shouldUseAction:forControlCharacterAtIndex: delegate method.