Mac Developer Library

Developer

ApplicationServices Framework Reference CTRun Reference

Options
Deployment Target:

On This Page
Language:

CTRun Reference

The CTRun opaque type represents a glyph run, which is a set of consecutive glyphs sharing the same attributes and direction.

The typesetter creates glyph runs as it produces lines from character strings, attributes, and font objects. That is, a line is constructed of one or more glyphs runs. Glyph runs can draw themselves into a graphic context, if desired, although most users have no need to interact directly with glyph runs.

Functions

  • Gets the glyph count for the run.

    Declaration

    Swift

    func CTRunGetGlyphCount(_ run: CTRun!) -> CFIndex

    Objective-C

    CFIndex CTRunGetGlyphCount ( CTRunRef run );

    Parameters

    run

    The run for which to return the glyph count.

    Return Value

    The number of glyphs that the run contains, or if there are no glyphs in this run, a value of 0.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Returns the attribute dictionary that was used to create the glyph run.

    Declaration

    Swift

    func CTRunGetAttributes(_ run: CTRun!) -> CFDictionary!

    Objective-C

    CFDictionaryRef CTRunGetAttributes ( CTRunRef run );

    Parameters

    run

    The run for which to return attributes.

    Return Value

    A valid CFDictionaryRef or NULL on error or if the run has no attributes.

    Discussion

    The dictionary returned is either the same one that was set as an attribute dictionary on the original attributed string or a dictionary that has been manufactured by the layout engine. Attribute dictionaries can be manufactured in the case of font substitution or if the run is missing critical attributes.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Returns the run's status.

    Declaration

    Swift

    func CTRunGetStatus(_ run: CTRun!) -> CTRunStatus

    Objective-C

    CTRunStatus CTRunGetStatus ( CTRunRef run );

    Parameters

    run

    The run for which to return the status.

    Return Value

    The run's status.

    Discussion

    Runs have status that can be used to expedite certain operations. Knowing the direction and ordering of a run's glyphs can aid in string index analysis, whereas knowing whether the positions reference the identity text matrix can avoid expensive comparisons. This status is provided as a convenience, because this information is not strictly necessary but can be helpful in some circumstances.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Returns a direct pointer for the glyph array stored in the run.

    Declaration

    Swift

    func CTRunGetGlyphsPtr(_ run: CTRun!) -> UnsafePointer<CGGlyph>

    Objective-C

    const CGGlyph * CTRunGetGlyphsPtr ( CTRunRef run );

    Parameters

    run

    The run from which to return glyphs.

    Return Value

    A valid pointer to an array of CGGlyph structures, or NULL.

    Discussion

    The glyph array will have a length equal to the value returned by CTRunGetGlyphCount. The caller should be prepared for this function to return NULL even if there are glyphs in the stream. If this function returns NULL, the caller must allocate its own buffer and call CTRunGetGlyphs to fetch the glyphs.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Copies a range of glyphs into a user-provided buffer.

    Declaration

    Swift

    func CTRunGetGlyphs(_ run: CTRun!, _ range: CFRange, _ buffer: UnsafeMutablePointer<CGGlyph>)

    Objective-C

    void CTRunGetGlyphs ( CTRunRef run, CFRange range, CGGlyph buffer[] );

    Parameters

    run

    The run from which to copy glyphs.

    range

    The range of glyphs to copy. If the length of the range is set to 0, then the copy operation continues from the range's start index to the end of the run.

    buffer

    The buffer the glyphs are copied to. The buffer must be allocated to at least the value specified by the range's length.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Returns a direct pointer for the glyph position array stored in the run.

    Declaration

    Swift

    func CTRunGetPositionsPtr(_ run: CTRun!) -> UnsafePointer<CGPoint>

    Objective-C

    const CGPoint * CTRunGetPositionsPtr ( CTRunRef run );

    Parameters

    run

    The run from which to access glyph positions.

    Return Value

    A valid pointer to an array of CGPoint structures, or NULL.

    Discussion

    The glyph positions in a run are relative to the origin of the line containing the run. The position array will have a length equal to the value returned by CTRunGetGlyphCount. The caller should be prepared for this function to return NULL even if there are glyphs in the stream. If this function returns NULL, the caller must allocate its own buffer and call CTRunGetPositions to fetch the glyph positions.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Copies a range of glyph positions into a user-provided buffer.

    Declaration

    Swift

    func CTRunGetPositions(_ run: CTRun!, _ range: CFRange, _ buffer: UnsafeMutablePointer<CGPoint>)

    Objective-C

    void CTRunGetPositions ( CTRunRef run, CFRange range, CGPoint buffer[] );

    Parameters

    run

    The run from which to copy glyph positions.

    range

    The range of glyph positions to copy. If the length of the range is set to 0, then the copy operation will continue from the start index of the range to the end of the run.

    buffer

    The buffer to which the glyph positions are copied. The buffer must be allocated to at least the value specified by the range's length.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Returns a direct pointer for the glyph advance array stored in the run.

    Declaration

    Swift

    func CTRunGetAdvancesPtr(_ run: CTRun!) -> UnsafePointer<CGSize>

    Objective-C

    const CGSize * CTRunGetAdvancesPtr ( CTRunRef run );

    Parameters

    run

    The run whose advances you wish to access.

    Return Value

    A valid pointer to an array of CGSize structures representing the glyph advance array or NULL.

    Discussion

    The advance array will have a length equal to the value returned by CTRunGetGlyphCount. The caller should be prepared for this function to return NULL even if there are glyphs in the stream. Should this function return NULL, the caller needs allocate its own buffer and call CTRunGetAdvances to fetch the advances. Note that advances alone are not sufficient for correctly positioning glyphs in a line, as a run may have a non-identity matrix or the initial glyph in a line may have a non-zero origin; callers should consider using positions instead.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Copies a range of glyph advances into a user-provided buffer.

    Declaration

    Swift

    func CTRunGetAdvances(_ run: CTRun!, _ range: CFRange, _ buffer: UnsafeMutablePointer<CGSize>)

    Objective-C

    void CTRunGetAdvances ( CTRunRef run, CFRange range, CGSize buffer[] );

    Parameters

    run

    The run whose advances you wish to copy.

    range

    The range of glyph advances you wish to copy. If the length of the range is set to 0, then the copy operation continues from the range's start index to the end of the run.

    buffer

    The buffer to which the glyph advances are copied. The buffer must be allocated to at least the value specified by the range's length.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Returns a direct pointer for the string indices stored in the run.

    Declaration

    Swift

    func CTRunGetStringIndicesPtr(_ run: CTRun!) -> UnsafePointer<CFIndex>

    Objective-C

    const CFIndex * CTRunGetStringIndicesPtr ( CTRunRef run );

    Parameters

    run

    The run for which to return string indices.

    Return Value

    A valid pointer to an array of CFIndex structures, or NULL.

    Discussion

    The indices are the character indices that originally spawned the glyphs that make up the run. They can be used to map the glyphs in the run back to the characters in the backing store. The string indices array will have a length equal to the value returned by CTRunGetGlyphCount. The caller should be prepared for this function to return NULL even if there are glyphs in the stream. If this function returns NULL, the caller must allocate its own buffer and call CTRunGetStringIndices to fetch the indices.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Copies a range of string indices into a user-provided buffer.

    Declaration

    Swift

    func CTRunGetStringIndices(_ run: CTRun!, _ range: CFRange, _ buffer: UnsafeMutablePointer<CFIndex>)

    Objective-C

    void CTRunGetStringIndices ( CTRunRef run, CFRange range, CFIndex buffer[] );

    Parameters

    run

    The run from which to copy the string indices.

    range

    The range of string indices to copy. If the length of the range is set to 0, then the copy operation continues from the range's start index to the end of the run.

    buffer

    The buffer to which the string indices are copied. The buffer must be allocated to at least the value specified by the range's length.

    Discussion

    The indices are the character indices that originally spawned the glyphs that make up the run. They can be used to map the glyphs in the run back to the characters in the backing store.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Gets the range of characters that originally spawned the glyphs in the run.

    Declaration

    Swift

    func CTRunGetStringRange(_ run: CTRun!) -> CFRange

    Objective-C

    CFRange CTRunGetStringRange ( CTRunRef run );

    Parameters

    run

    The run for which to access the string range.

    Return Value

    The range of characters that originally spawned the glyphs, of if run is invalid, an empty range.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Gets the typographic bounds of the run.

    Declaration

    Swift

    func CTRunGetTypographicBounds(_ run: CTRun!, _ range: CFRange, _ ascent: UnsafeMutablePointer<CGFloat>, _ descent: UnsafeMutablePointer<CGFloat>, _ leading: UnsafeMutablePointer<CGFloat>) -> Double

    Objective-C

    double CTRunGetTypographicBounds ( CTRunRef run, CFRange range, CGFloat *ascent, CGFloat *descent, CGFloat *leading );

    Parameters

    run

    The run for which to calculate the typographic bounds.

    range

    The portion of the run to measure. If the length of the range is set to 0, then the measure operation continues from the range's start index to the end of the run.

    ascent

    On output, the ascent of the run. This can be set to NULL if not needed.

    descent

    On output, the descent of the run. This can be set to NULL if not needed.

    leading

    On output, the leading of the run. This can be set to NULL if not needed.

    Return Value

    The typographic width of the run, or if run or range is invalid, 0.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Calculates the image bounds for a glyph range.

    Declaration

    Swift

    func CTRunGetImageBounds(_ run: CTRun!, _ context: CGContext!, _ range: CFRange) -> CGRect

    Objective-C

    CGRect CTRunGetImageBounds ( CTRunRef run, CGContextRef context, CFRange range );

    Parameters

    run

    The run for which to calculate the image bounds.

    context

    The context for the image bounds being calculated. This is required because the context could have settings in it that would cause changes in the image bounds.

    range

    The portion of the run to measure. If the length of the range is set to 0, then the measure operation continues from the start index of the range to the end of the run.

    Return Value

    A rectangle that tightly encloses the paths of the run's glyphs, or, if run, context, or range is invalid, CGRectNull.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Draws a complete run or part of one.

    Declaration

    Swift

    func CTRunDraw(_ run: CTRun!, _ context: CGContext!, _ range: CFRange)

    Objective-C

    void CTRunDraw ( CTRunRef run, CGContextRef context, CFRange range );

    Parameters

    run

    The run to draw.

    context

    The context into which to draw the run.

    range

    The portion of the run to draw. If the length of the range is set to 0, then the draw operation continues from the start index of the range to the end of the run.

    Discussion

    This is a convenience call, because the run could be drawn by accessing the glyphs. This call can leave the graphics context in any state and does not flush the context after the draw operation.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Returns the text matrix needed to draw this run.

    Declaration

    Swift

    func CTRunGetTextMatrix(_ run: CTRun!) -> CGAffineTransform

    Objective-C

    CGAffineTransform CTRunGetTextMatrix ( CTRunRef run );

    Parameters

    run

    The run object from which to get the text matrix.

    Return Value

    A CGAffineTransform structure.

    Discussion

    To properly draw the glyphs in a run, the fields tx and ty of the CGAffineTransform returned by this function should be set to the current text position.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

  • Returns the Core Foundation type identifier of the run object.

    Declaration

    Swift

    func CTRunGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CTRunGetTypeID ( void );

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.

Data Types

  • A reference to a run object.

    Declaration

    Swift

    typealias CTRunRef = CTRun

    Objective-C

    typedef const struct __CTRun *CTRunRef;

    Availability

    Available in OS X v10.5 and later.

Constants

  • A bitfield passed back by the CTRunGetStatus function that is used to indicate the disposition of the run.

    Declaration

    Swift

    struct CTRunStatus : RawOptionSetType { init(_ rawValue: UInt32) init(rawValue rawValue: UInt32) static var NoStatus: CTRunStatus { get } static var RightToLeft: CTRunStatus { get } static var NonMonotonic: CTRunStatus { get } static var HasNonIdentityMatrix: CTRunStatus { get } }

    Objective-C

    enum{ kCTRunStatusNoStatus = 0, kCTRunStatusRightToLeft = (1 << 0), kCTRunStatusNonMonotonic = (1 << 1), kCTRunStatusHasNonIdentityMatrix = (1 << 2) }; typedef uint32_t CTRunStatus;

    Constants

    • NoStatus

      kCTRunStatusNoStatus

      The run has no special attributes.

      Available in OS X v10.5 and later.

    • RightToLeft

      kCTRunStatusRightToLeft

      The run proceeds from right to left.

      Available in OS X v10.5 and later.

    • NonMonotonic

      kCTRunStatusNonMonotonic

      The run has been reordered in some way such that the string indices associated with the glyphs are no longer strictly increasing (for left-to-right runs) or decreasing (for right-to-left runs).

      Available in OS X v10.5 and later.

    • HasNonIdentityMatrix

      kCTRunStatusHasNonIdentityMatrix

      The run requires a specific text matrix to be set in the current Core Graphics context for proper drawing.

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in OS X v10.5 and later.