Mac Developer Library

Developer

AppKit Framework Reference NSTypesetter Class Reference

Options
Deployment Target:

On This Page
Language:

NSTypesetter

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

NSLayoutManager uses concrete subclasses of this abstract class, NSTypesetter, to perform line layout, which includes word wrapping, hyphenation, and line breaking in either vertical or horizontal rectangles. By default, the text system uses the concrete subclass NSATSTypesetter.

Subclassing Notes

NSTypesetter provides concrete subclasses with default implementation interfacing with the Cocoa text system. By subclassing NSTypesetter, an application can override the layoutParagraphAtPoint: method to integrate a custom typesetting engine into the Cocoa text system. On the other hand, an application can subclass NSATSTypesetter and override the glyph storage interface to integrate the concrete subclass into its own custom layout system.

NSTypesetter methods belong to three categories: glyph storage interface methods, layout phase interface methods, and core typesetter methods. The glyph storage interface methods map to NSLayoutManager methods. The typesetter itself calls these methods, and their default implementations call the Cocoa layout manager. An NSTypesetter subclass can override these methods to call its own glyph storage facility, in which case it should override all of them. (This does not preclude the overridden method calling its superclass implementation if appropriate.)

The layout phase interface provides control points similar to delegate methods; if implemented, the system invokes these methods to notify an NSTypesetter subclass of events in the layout process so it can intervene as needed.

The remainder of the NSTypesetter methods are primitive, core typesetter methods. The core typesetter methods correlate with typesetting state attributes; the layout manager calls these methods to store its values before starting the layout process. If you subclass NSTypesetter and override the glyph storage interface methods, you can call the core methods to control the typesetter directly.

Glyph Storage Interface

Override these methods to use NSTypesetter’s built-in concrete subclass, NSATSTypesetter, with a custom glyph storage and layout system other than the Cocoa layout manager and text container mechanism.

Layout Phase Interface

Override these methods to customize the text layout process, including modifying line fragments, controlling line breaking and hyphenation, and controlling the behavior of tabs and other control glyphs.

  • Returns the interglyph spacing in the specified range when sent to a printer.

    Declaration

    Swift

    class func printingAdjustmentInLayoutManager(_ layoutMgr: NSLayoutManager, forNominallySpacedGlyphRange nominallySpacedGlyphsRange: NSRange, packedGlyphs packedGlyphs: UnsafePointer<UInt8>, count packedGlyphsCount: Int) -> NSSize

    Objective-C

    + (NSSize)printingAdjustmentInLayoutManager:(NSLayoutManager *)layoutMgr forNominallySpacedGlyphRange:(NSRange)nominallySpacedGlyphsRange packedGlyphs:(const unsigned char *)packedGlyphs count:(NSUInteger)packedGlyphsCount

    Parameters

    layoutMgr

    The layout manager that will do the drawing.

    nominallySpacedGlyphsRange

    The range of the glyphs whose spacing is desired.

    packedGlyphs

    The glyphs as they are packed for sending to be drawn in layoutMgr.

    packedGlyphsCount

    The number of glyphs in packedGlyphs.

    Return Value

    The interglyph spacing in the specified range when sent to a printer. If the font metrics of the font used for displaying text on the screen is different from the font metrics of the font used in printing, then this interglyph spacing may need to be adjusted slightly to match that used on the screen.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the distance from the bottom of the line fragment rectangle in which the glyph resides to the glyph baseline.

    Declaration

    Swift

    func baselineOffsetInLayoutManager(_ layoutMgr: NSLayoutManager, glyphIndex glyphIndex: Int) -> CGFloat

    Objective-C

    - (CGFloat)baselineOffsetInLayoutManager:(NSLayoutManager *)layoutMgr glyphIndex:(NSUInteger)glyphIndex

    Parameters

    layoutMgr

    The layout manager used for the drawing.

    glyphIndex

    The index of the glyph in question.

    Return Value

    The distance from the bottom of the line fragment rectangle in which the glyph resides to the glyph baseline.

    Discussion

    The text system uses this value to calculate the vertical position of underlines.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the layout manager for the text being typeset.

    Declaration

    Swift

    unowned(unsafe) var layoutManager: NSLayoutManager? { get }

    Objective-C

    @property(readonly, assign) NSLayoutManager *layoutManager

    Return Value

    The layout manager for the text being typeset. This value is valid only while the typesetter is performing layout.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets whether the typesetter uses the leading (or line gap) value specified in the font metric information.

    Declaration

    Swift

    var usesFontLeading: Bool

    Objective-C

    @property BOOL usesFontLeading

    Parameters

    flag

    YEStrue to use the information in the font metrics, NOfalse to ignore it.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns whether the typesetter uses the leading (or line gap) value specified in the font metric information of the current font.

    Declaration

    Swift

    var usesFontLeading: Bool

    Objective-C

    @property BOOL usesFontLeading

    Return Value

    YEStrue if it uses the information in the font metrics, NOfalse otherwise.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the default typesetter behavior, which affects glyph spacing and line height.

    Declaration

    Swift

    var typesetterBehavior: NSTypesetterBehavior

    Objective-C

    @property NSTypesetterBehavior typesetterBehavior

    Parameters

    behavior

    The new behavior.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the current typesetter behavior.

    Declaration

    Swift

    var typesetterBehavior: NSTypesetterBehavior

    Objective-C

    @property NSTypesetterBehavior typesetterBehavior

    Return Value

    The current typesetter behavior.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the threshold controlling when hyphenation is attempted.

    Declaration

    Swift

    var hyphenationFactor: Float

    Objective-C

    @property float hyphenationFactor

    Parameters

    factor

    A frequency factor in the range of 0.0 to 1.0. By default, the value is 0.0, meaning hyphenation is off. A factor of 1.0 causes hyphenation to be attempted always.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the current hyphenation factor.

    Declaration

    Swift

    var hyphenationFactor: Float

    Objective-C

    @property float hyphenationFactor

    Return Value

    The hyphenation factor, a value ranging from 0.0 to 1.0 that controls when hyphenation is attempted. By default, the value is 0.0, meaning hyphenation is off. A factor of 1.0 causes hyphenation to be attempted always.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the text container for the text being typeset.

    Declaration

    Swift

    unowned(unsafe) var currentTextContainer: NSTextContainer? { get }

    Objective-C

    @property(readonly, assign) NSTextContainer *currentTextContainer

    Return Value

    The text container for the text being typeset. This value is valid only while the typesetter is performing layout.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns an array containing the text containers belonging to the current layout manager.

    Declaration

    Swift

    var textContainers: [AnyObject]? { get }

    Objective-C

    @property(readonly, assign) NSArray *textContainers

    Return Value

    An array containing the text containers belonging to the current layout manager. This value is valid only while the typesetter is performing layout.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the amount (in points) by which text is inset within line fragment rectangles.

    Declaration

    Swift

    var lineFragmentPadding: CGFloat

    Objective-C

    @property CGFloat lineFragmentPadding

    Parameters

    padding

    The amount (in points) by which text is inset within line fragment rectangles.

    Special Considerations

    Line fragment padding isn’t a suitable means for expressing margins; you should set the text view's position and size for document margins or the paragraph margin attributes for text margins.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the current line fragment padding, in points.

    Declaration

    Swift

    var lineFragmentPadding: CGFloat

    Objective-C

    @property CGFloat lineFragmentPadding

    Return Value

    The current line fragment padding, in points; that is, the portion on each end of the line fragment rectangle left blank.

    Discussion

    Text is inset within the line fragment rectangle by this amount.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns a screen font suitable for use in place of a given font.

    Declaration

    Swift

    func substituteFontForFont(_ originalFont: NSFont) -> NSFont

    Objective-C

    - (NSFont *)substituteFontForFont:(NSFont *)originalFont

    Parameters

    originalFont

    The original font.

    Return Value

    A screen font suitable for use in place of originalFont. This method returns originalFont if a screen font can’t be used or isn’t available.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Controls whether the typesetter performs bidirectional text processing.

    Declaration

    Swift

    var bidiProcessingEnabled: Bool

    Objective-C

    @property BOOL bidiProcessingEnabled

    Parameters

    flag

    YEStrue to enable bidirectional text processing, NOfalse to disable it.

    Discussion

    You can use this method to disable the bidirectional layout stage if you know the paragraph does not need this stage; that is, if the characters in the backing store are in display order.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns whether bidirectional text processing is enabled.

    Declaration

    Swift

    var bidiProcessingEnabled: Bool

    Objective-C

    @property BOOL bidiProcessingEnabled

    Return Value

    YEStrue if bidirectional text processing is enabled, NOfalse otherwise.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Lays out glyphs in the current glyph range until the next paragraph separator is reached.

    Declaration

    Swift

    func layoutParagraphAtPoint(_ lineFragmentOrigin: NSPointPointer) -> Int

    Objective-C

    - (NSUInteger)layoutParagraphAtPoint:(NSPointPointer)lineFragmentOrigin

    Parameters

    lineFragmentOrigin

    The upper-left corner of line fragment rectangle. On return, lineFragmentOrigin contains the next origin.

    Return Value

    The next glyph index; usually the index right after the paragraph separator, but it can be inside the paragraph range if, for example, the end of the text container is reached before the paragraph separator.

    Discussion

    Concrete subclasses must implement this method. A concrete implementation must invoke beginParagraph, beginLineWithGlyphAtIndex:, endLineWithGlyphRange:, and endParagraph.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets up layout parameters at the beginning of a paragraph.

    Declaration

    Swift

    func beginParagraph()

    Objective-C

    - (void)beginParagraph

    Discussion

    Concrete subclasses should invoke this method at the beginning of their layoutParagraphAtPoint: implementation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets up layout parameters at the end of a paragraph.

    Declaration

    Swift

    func endParagraph()

    Objective-C

    - (void)endParagraph

    Discussion

    Concrete subclasses should invoke this method at the end of their layoutParagraphAtPoint: implementation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets up layout parameters at the beginning of a line during typesetting.

    Declaration

    Swift

    func beginLineWithGlyphAtIndex(_ glyphIndex: Int)

    Objective-C

    - (void)beginLineWithGlyphAtIndex:(NSUInteger)glyphIndex

    Parameters

    glyphIndex

    The index of the first glyph to be laid out in the line.

    Discussion

    Concrete subclass implementations of layoutParagraphAtPoint: should invoke this method at the beginning of each line.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets up layout parameters at the end of a line during typesetting.

    Declaration

    Swift

    func endLineWithGlyphRange(_ lineGlyphRange: NSRange)

    Objective-C

    - (void)endLineWithGlyphRange:(NSRange)lineGlyphRange

    Parameters

    lineGlyphRange

    The range of glyphs laid out in the line.

    Discussion

    Concrete subclass implementations of layoutParagraphAtPoint: should invoke this method at the end of each line.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Lays out characters in the given character range for the specified layout manager.

    Declaration

    Swift

    func layoutCharactersInRange(_ characterRange: NSRange, forLayoutManager layoutManager: NSLayoutManager, maximumNumberOfLineFragments maxNumLines: Int) -> NSRange

    Objective-C

    - (NSRange)layoutCharactersInRange:(NSRange)characterRange forLayoutManager:(NSLayoutManager *)layoutManager maximumNumberOfLineFragments:(NSUInteger)maxNumLines

    Parameters

    characterRange

    The range of the characters to lay out.

    layoutManager

    The layout manager that does the drawing.

    maxNumLines

    The maximum number of line fragments to lay out. Specify NSUIntegerMax for unlimited number of line fragments.

    Return Value

    The method returns the actual character range that the receiving NSTypesetter processed.

    Discussion

    The layout process can be interrupted when the number of line fragments exceeds maxNumLines.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets whether to force the layout manager to invalidate the specified portion of the glyph cache when invalidating layout.

    Declaration

    Swift

    func setHardInvalidation(_ flag: Bool, forGlyphRange glyphRange: NSRange)

    Objective-C

    - (void)setHardInvalidation:(BOOL)flag forGlyphRange:(NSRange)glyphRange

    Parameters

    flag

    YEStrue if the layout manager should invalidate the specified portion of the glyph cache, NOfalse otherwise.

    glyphRange

    The range of glyphs in the cache to be marked for hard invalidation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Lays out glyphs in the specified layout manager starting at a specified glyph.

    Use layoutCharactersInRange:forLayoutManager:maximumNumberOfLineFragments: instead.

    Declaration

    Swift

    func layoutGlyphsInLayoutManager(_ layoutMgr: NSLayoutManager, startingAtGlyphIndex startGlyphIndex: Int, maxNumberOfLineFragments maxNumLines: Int, nextGlyphIndex nextGlyph: UnsafeMutablePointer<Int>)

    Objective-C

    - (void)layoutGlyphsInLayoutManager:(NSLayoutManager *)layoutMgr startingAtGlyphIndex:(NSUInteger)startGlyphIndex maxNumberOfLineFragments:(NSUInteger)maxNumLines nextGlyphIndex:(NSUInteger *)nextGlyph

    Parameters

    layoutMgr

    The layout manager in which to lay out glyphs.

    startGlyphIndex

    The index of the starting glyph.

    maxNumLines

    The maximum number of lines to generate. Fewer lines may be laid out if the glyph storage runs out of glyphs.

    nextGlyph

    On return, set to the index of the next glyph that needs to be laid out.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the bounding rectangle for the specified control glyph with the specified parameters.

    Declaration

    Swift

    func boundingBoxForControlGlyphAtIndex(_ glyphIndex: Int, forTextContainer textContainer: NSTextContainer, proposedLineFragment proposedRect: NSRect, glyphPosition glyphPosition: NSPoint, characterIndex charIndex: Int) -> NSRect

    Objective-C

    - (NSRect)boundingBoxForControlGlyphAtIndex:(NSUInteger)glyphIndex forTextContainer:(NSTextContainer *)textContainer proposedLineFragment:(NSRect)proposedRect glyphPosition:(NSPoint)glyphPosition characterIndex:(NSUInteger)charIndex

    Parameters

    glyphIndex

    The index of the control glyph in question.

    textContainer

    The text container to use to calculate the position.

    proposedRect

    The proposed line fragment rectangle.

    glyphPosition

    The position of the glyph in textContainer.

    charIndex

    The character index in textContainer.

    Return Value

    The bounding rectangle of the control glyph at glyphIndex, at the given glyphPosition and character index charIndex, in textContainer.

    Discussion

    The typesetter calls this method when it encounters a control glyph. The default behavior is to return zero width for control glyphs. A subclass can override this method to do something different, such as implement a way to display control characters.

    NSGlyphGenerator can choose whether or not to map control characters to NSControlGlyph. Tab characters, for example, do not use this facility.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Calculates the line fragment rectangle and line fragment used rectangle for blank lines.

    Declaration

    Swift

    func getLineFragmentRect(_ lineFragmentRect: NSRectPointer, usedRect lineFragmentUsedRect: NSRectPointer, forParagraphSeparatorGlyphRange paragraphSeparatorGlyphRange: NSRange, atProposedOrigin lineOrigin: NSPoint)

    Objective-C

    - (void)getLineFragmentRect:(NSRectPointer)lineFragmentRect usedRect:(NSRectPointer)lineFragmentUsedRect forParagraphSeparatorGlyphRange:(NSRange)paragraphSeparatorGlyphRange atProposedOrigin:(NSPoint)lineOrigin

    Parameters

    lineFragmentRect

    On return, the calculated line fragment rectangle.

    lineFragmentUsedRect

    On return, the used rectangle (the portion of the line fragment rectangle that actually contains marks).

    paragraphSeparatorGlyphRange

    The range of glyphs under consideration. A paragraphSeparatorGlyphRange with length 0 indicates an extra line fragment (which occurs if the last character in the paragraph is a line separator).

    lineOrigin

    The origin point of the line fragment rectangle.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Calculates line fragment rectangle, line fragment used rectangle, and remaining rectangle for a line fragment.

    Declaration

    Swift

    func getLineFragmentRect(_ lineFragmentRect: NSRectPointer, usedRect lineFragmentUsedRect: NSRectPointer, remainingRect remainingRect: NSRectPointer, forStartingGlyphAtIndex startingGlyphIndex: Int, proposedRect proposedRect: NSRect, lineSpacing lineSpacing: CGFloat, paragraphSpacingBefore paragraphSpacingBefore: CGFloat, paragraphSpacingAfter paragraphSpacingAfter: CGFloat)

    Objective-C

    - (void)getLineFragmentRect:(NSRectPointer)lineFragmentRect usedRect:(NSRectPointer)lineFragmentUsedRect remainingRect:(NSRectPointer)remainingRect forStartingGlyphAtIndex:(NSUInteger)startingGlyphIndex proposedRect:(NSRect)proposedRect lineSpacing:(CGFloat)lineSpacing paragraphSpacingBefore:(CGFloat)paragraphSpacingBefore paragraphSpacingAfter:(CGFloat)paragraphSpacingAfter

    Parameters

    lineFragmentRect

    On return, the calculated line fragment rectangle.

    lineFragmentUsedRect

    On return, the used rectangle (the portion of the line fragment rectangle that actually contains marks).

    remainingRect

    On return, the remaining rectangle of proposedRect.

    startingGlyphIndex

    The glyph index where the line fragment starts.

    proposedRect

    The proposed rectangle of the line fragment.

    lineSpacing

    The line spacing.

    paragraphSpacingBefore

    The spacing before the paragraph.

    paragraphSpacingAfter

    The spacing after the paragraph.

    Discussion

    The height of the line fragment is determined using lineSpacing, paragraphSpacingBefore, and paragraphSpacingAfter as well as proposedRect. The width for lineFragmentUsedRect is set to the lineFragmentRect width. In the standard implementation, paragraph spacing is included in the line fragment rectangle but not the line fragment used rectangle; line spacing is included in both.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the hyphen character to be inserted after the specified glyph.

    Declaration

    Swift

    func hyphenCharacterForGlyphAtIndex(_ glyphIndex: Int) -> UTF32Char

    Objective-C

    - (UTF32Char)hyphenCharacterForGlyphAtIndex:(NSUInteger)glyphIndex

    Parameters

    glyphIndex

    The index of the glyph in question.

    Return Value

    The hyphen character to be inserted after the glyph at glyphIndex.

    Discussion

    The typesetter calls this method before hyphenating. A subclass can override this method to return a different hyphen glyph.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the hyphenation factor in effect at a specified location.

    Declaration

    Swift

    func hyphenationFactorForGlyphAtIndex(_ glyphIndex: Int) -> Float

    Objective-C

    - (float)hyphenationFactorForGlyphAtIndex:(NSUInteger)glyphIndex

    Parameters

    glyphIndex

    The index of the glyph position to examine.

    Return Value

    The hyphenation factor in effect at glyphIndex. The hyphenation factor is a value ranging from 0.0 to 1.0 that controls when hyphenation is attempted. By default, the value is 0.0, meaning hyphenation is off. A factor of 1.0 causes hyphenation to be attempted always.

    Discussion

    The typesetter calls this method with a proposed hyphenation point for a line break to find the hyphenation factor in effect at that time. A subclass can override this method to customize the text layout process.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns whether the line being laid out should be broken by hyphenating at the specified character.

    Declaration

    Swift

    func shouldBreakLineByHyphenatingBeforeCharacterAtIndex(_ charIndex: Int) -> Bool

    Objective-C

    - (BOOL)shouldBreakLineByHyphenatingBeforeCharacterAtIndex:(NSUInteger)charIndex

    Parameters

    charIndex

    The index of the character just after the proposed hyphenation would occur.

    Return Value

    YEStrue if the line should be broken by hyphenating, NOfalse otherwise.

    Discussion

    The typesetter calls this method, if implemented by a subclass, before breaking a line by hyphenating before the character at charIndex, enabling the subclass to control line breaking.

    A subclass can override this method to customize the text layout process. If the method returns NOfalse, the typesetter continues looking for a break point.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns whether the line being laid out should be broken by a word break at the specified character.

    Declaration

    Swift

    func shouldBreakLineByWordBeforeCharacterAtIndex(_ charIndex: Int) -> Bool

    Objective-C

    - (BOOL)shouldBreakLineByWordBeforeCharacterAtIndex:(NSUInteger)charIndex

    Parameters

    charIndex

    The index of the character just after the proposed word break would occur.

    Return Value

    YEStrue if the line should be broken by a word break, NOfalse otherwise.

    Discussion

    The typesetter calls this method, if implemented by a subclass, before breaking a line by word wrapping before the character at charIndex, enabling the subclass to control line breaking.

    A subclass can override this method to customize the text layout process. If the method returns NOfalse, the typesetter continues looking for a break point.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Called by the typesetter just prior to storing the actual line fragment rectangle location in the layout manager.

    Declaration

    Swift

    func willSetLineFragmentRect(_ lineRect: NSRectPointer, forGlyphRange glyphRange: NSRange, usedRect usedRect: NSRectPointer, baselineOffset baselineOffset: UnsafeMutablePointer<CGFloat>)

    Objective-C

    - (void)willSetLineFragmentRect:(NSRectPointer)lineRect forGlyphRange:(NSRange)glyphRange usedRect:(NSRectPointer)usedRect baselineOffset:(CGFloat *)baselineOffset

    Parameters

    lineRect

    The rectangle in which the glyphs in glyphRange are laid out.

    glyphRange

    The range of the glyphs to lay out.

    usedRect

    The portion of lineRect, in the NSTextContainer object’s coordinate system, that actually contains glyphs or other marks that are drawn (including the text container’s line fragment padding). The usedRect must be equal to or contained within lineRect.

    baselineOffset

    The vertical distance in pixels from the line fragment origin to the baseline on which the glyphs align.

    Discussion

    Called by the typesetter just prior to calling setLineFragmentRect:forGlyphRange:usedRect:baselineOffset: which stores the actual line fragment rectangle location in the layout manager.

    A subclass can override this method to customize the text layout process. For example, it could change the shape of the line fragment rectangle. The subclass is responsible for ensuring that the modified rectangle remains valid (for example, that it lies within the text container).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func characterRangeForGlyphRange(_ glyphRange: NSRange, actualGlyphRange actualGlyphRange: NSRangePointer) -> NSRange

    Objective-C

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

    Parameters

    glyphRange

    The range of glyphs.

    actualGlyphRange

    On return, the range of all glyphs mapped to the characters in the receiver’s text store. May be NULL.

    Return Value

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

    Discussion

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Deletes the specified glyphs from the glyph cache maintained by the layout manager.

    Declaration

    Swift

    func deleteGlyphsInRange(_ glyphRange: NSRange)

    Objective-C

    - (void)deleteGlyphsInRange:(NSRange)glyphRange

    Parameters

    glyphRange

    The range of glyphs to be deleted.

    Discussion

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Replaces the specified glyphs with specified replacement glyphs.

    Declaration

    Swift

    func substituteGlyphsInRange(_ glyphRange: NSRange, withGlyphs glyphs: UnsafeMutablePointer<NSGlyph>)

    Objective-C

    - (void)substituteGlyphsInRange:(NSRange)glyphRange withGlyphs:(NSGlyph *)glyphs

    Parameters

    glyphRange

    The range of glyphs to be substituted.

    glyphs

    The glyphs to substitute for the glyphs in glyphRange.

    Discussion

    This method does not alter the glyph-to-character mapping or invalidate layout information.

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Extracts the information needed to lay out the provided glyphs from the provided range.

    Declaration

    Swift

    func getGlyphsInRange(_ glyphsRange: NSRange, glyphs glyphBuffer: UnsafeMutablePointer<NSGlyph>, characterIndexes charIndexBuffer: UnsafeMutablePointer<Int>, glyphInscriptions inscribeBuffer: UnsafeMutablePointer<NSGlyphInscription>, elasticBits elasticBuffer: UnsafeMutablePointer<ObjCBool>, bidiLevels bidiLevelBuffer: UnsafeMutablePointer<UInt8>) -> Int

    Objective-C

    - (NSUInteger)getGlyphsInRange:(NSRange)glyphsRange glyphs:(NSGlyph *)glyphBuffer characterIndexes:(NSUInteger *)charIndexBuffer glyphInscriptions:(NSGlyphInscription *)inscribeBuffer elasticBits:(BOOL *)elasticBuffer bidiLevels:(unsigned char *)bidiLevelBuffer

    Parameters

    glyphsRange

    The range of glyphs.

    glyphBuffer

    The glyphs to lay out.

    charIndexBuffer

    The original characters for the glyphs. Note that a glyph at index 1 is not necessarily mapped to the character at index 1, because a glyph may be for a ligature or accent.

    inscribeBuffer

    The inscription attributes for each glyph, which are used to layout characters that are combined together.

    elasticBuffer

    Contains a Boolean value indicating whether a glyph is elastic for each glyph. An elastic glyph can be made longer at the end of a line or when needed for justification.

    bidiLevelBuffer

    Contains the bidirectional level value generated by NSGlyphGenerator, in case a subclass chooses to use this value.

    Discussion

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func glyphRangeForCharacterRange(_ charRange: NSRange, actualCharacterRange actualCharRange: NSRangePointer) -> NSRange

    Objective-C

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

    Parameters

    charRange

    The range of the characters whose glyph range is desired.

    actualCharRange

    On return, all characters mapped to those glyphs; may be NULL.

    Return Value

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

    Discussion

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Enables the typesetter to insert a new glyph into the stream.

    Declaration

    Swift

    func insertGlyph(_ glyph: NSGlyph, atGlyphIndex glyphIndex: Int, characterIndex charIndex: Int)

    Objective-C

    - (void)insertGlyph:(NSGlyph)glyph atGlyphIndex:(NSUInteger)glyphIndex characterIndex:(NSUInteger)charIndex

    Parameters

    glyph

    The glyph to insert into the glyph cache.

    glyphIndex

    The index at which to insert glyph.

    charIndex

    The index of the character that glyph maps to. If the glyph is mapped to several characters, charIndex should indicate the first character to which it’s mapped.

    Discussion

    The standard typesetter uses this method for inserting hyphenation glyphs. Because this method keeps the glyph caches synchronized, subclasses should always use this method to insert glyphs instead of calling layoutManager directly.

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the size the specified glyphs (assumed to be attachments) will be asked to draw themselves at.

    Declaration

    Swift

    func setAttachmentSize(_ attachmentSize: NSSize, forGlyphRange glyphRange: NSRange)

    Objective-C

    - (void)setAttachmentSize:(NSSize)attachmentSize forGlyphRange:(NSRange)glyphRange

    Parameters

    attachmentSize

    The size the glyphs in glyphRange (assumed to be attachments) will be asked to draw themselves at.

    glyphRange

    The range of glyphs the attachment size applies to.

    Discussion

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the direction of the specified glyphs for bidirectional text.

    Declaration

    Swift

    func setBidiLevels(_ levels: UnsafePointer<UInt8>, forGlyphRange glyphRange: NSRange)

    Objective-C

    - (void)setBidiLevels:(const uint8_t *)levels forGlyphRange:(NSRange)glyphRange

    Parameters

    levels

    Values in levels can range from 0 to 61 as defined by Unicode Standard Annex #9.

    glyphRange

    The range of glyphs for which the bidirectional text levels are desired.

    Discussion

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets whether the specified glyphs exceed the bounds of the line fragment in which they are laid out.

    Declaration

    Swift

    func setDrawsOutsideLineFragment(_ flag: Bool, forGlyphRange glyphRange: NSRange)

    Objective-C

    - (void)setDrawsOutsideLineFragment:(BOOL)flag forGlyphRange:(NSRange)glyphRange

    Parameters

    flag

    YEStrue if the glyphs in glyphRange exceed the bounds of the line fragment in which they are laid out, NOfalse otherwise.

    glyphRange

    The range of the glyphs in question.

    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.

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the line fragment rectangle where the specified glyphs are laid out.

    Declaration

    Swift

    func setLineFragmentRect(_ fragmentRect: NSRect, forGlyphRange glyphRange: NSRange, usedRect usedRect: NSRect, baselineOffset baselineOffset: CGFloat)

    Objective-C

    - (void)setLineFragmentRect:(NSRect)fragmentRect forGlyphRange:(NSRange)glyphRange usedRect:(NSRect)usedRect baselineOffset:(CGFloat)baselineOffset

    Parameters

    fragmentRect

    The line fragment rectangle where the glyphs in glyphRange are laid out.

    glyphRange

    The range of the specified glyphs.

    usedRect

    The portion of fragmentRect, in the NSTextContainer object’s coordinate system, that actually contains glyphs or other marks that are drawn (including the text container’s line fragment padding). The usedRect must be equal to or contained within fragmentRect.

    baselineOffset

    The vertical distance in pixels from the line fragment origin to the baseline on which the glyphs align.

    Discussion

    The exact positions of the glyphs must be set after the line fragment rectangle with setLocation:forStartOfGlyphRange:.

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the location where the specified glyphs are laid out.

    Declaration

    Swift

    func setLocation(_ location: NSPoint, withAdvancements advancements: UnsafePointer<CGFloat>, forStartOfGlyphRange glyphRange: NSRange)

    Objective-C

    - (void)setLocation:(NSPoint)location withAdvancements:(const CGFloat *)advancements forStartOfGlyphRange:(NSRange)glyphRange

    Parameters

    location

    The location where the glyphs in glyphRange are laid out. The x-coordinate of location is expressed relative to the line fragment rectangle origin, and the y-coordinate is expressed relative to the baseline previously specified by setLineFragmentRect:forGlyphRange:usedRect:baselineOffset:.

    advancements

    The nominal glyph advance width specified in the font metric information.

    glyphRange

    The range of glyphs whose layout location is being set. This series of glyphs can be displayed with a single PostScript show operation (a nominal range).

    Discussion

    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 line fragment rectangle with setLineFragmentRect:forGlyphRange:usedRect:baselineOffset:.

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets whether the specified glyphs are not shown.

    Declaration

    Swift

    func setNotShownAttribute(_ flag: Bool, forGlyphRange glyphRange: NSRange)

    Objective-C

    - (void)setNotShownAttribute:(BOOL)flag forGlyphRange:(NSRange)glyphRange

    Parameters

    flag

    YEStrue if the glyphs in glyphRange are not shown, NOfalse if they are shown.

    glyphRange

    The range of glyphs in question.

    Discussion

    For example, a tab or newline character doesn’t leave any marks; it just indicates where following glyphs are laid out.

    A subclass can override this method to interact with custom glyph storage.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The following constants are possible values returned by the actionForControlCharacterAtIndex: method to determine the action associated with a control character.

    Declaration

    Swift

    struct NSTypesetterControlCharacterAction : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var ZeroAdvancementAction: NSTypesetterControlCharacterAction { get } static var WhitespaceAction: NSTypesetterControlCharacterAction { get } static var HorizontalTabAction: NSTypesetterControlCharacterAction { get } static var LineBreakAction: NSTypesetterControlCharacterAction { get } static var ParagraphBreakAction: NSTypesetterControlCharacterAction { get } static var ContainerBreakAction: NSTypesetterControlCharacterAction { get } }

    Objective-C

    enum { NSTypesetterZeroAdvancementAction = (1 << 0), NSTypesetterWhitespaceAction = (1 << 1), NSTypesetterHorizontalTabAction = (1 << 2), NSTypesetterLineBreakAction = (1 << 3), NSTypesetterParagraphBreakAction = (1 << 4), NSTypesetterContainerBreakAction = (1 << 5) }; typedef NSUInteger NSTypesetterControlCharacterAction;

    Constants

    • ZeroAdvancementAction

      NSTypesetterZeroAdvancementAction

      Glyphs with this action are filtered out from layout (notShownAttribute == YES).

      Available in OS X v10.4 and later.

    • WhitespaceAction

      NSTypesetterWhitespaceAction

      The width for glyphs with this action are determined by boundingBoxForControlGlyphAtIndex:forTextContainer:proposedLineFragment:glyphPosition:characterIndex:, if the method is implemented; otherwise, same as NSTypesetterZeroAdvancementAction.

      Available in OS X v10.4 and later.

    • HorizontalTabAction

      NSTypesetterHorizontalTabAction

      Treated as tab character.

      Available in OS X v10.4 and later.

    • LineBreakAction

      NSTypesetterLineBreakAction

      Causes line break.

      Available in OS X v10.4 and later.

    • ParagraphBreakAction

      NSTypesetterParagraphBreakAction

      Causes paragraph break; the value returned by firstLineHeadIndent is the advancement used for the following glyph.

      Available in OS X v10.4 and later.

    • ContainerBreakAction

      NSTypesetterContainerBreakAction

      Causes container break.

      Available in OS X v10.4 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.