iOS Developer Library

Developer

CoreText Framework Reference CTRunDelegate Reference

Options
Deployment Target:

On This Page
Language:

CTRunDelegate Reference

The CTRunDelegate opaque type represents a run delegate, which is assigned to a run (attribute range) to control typographic traits such glyph ascent, glyph descent, and glyph width.

The callbacks defined for CTRunDelegate objects are provided by the owner of a run delegate and are used to modify glyph metrics during layout. The values returned by the delegate are applied to each glyph in the run or runs corresponding to the attribute with that delegate.

Functions

  • Creates an immutable instance of a run delegate.

    Declaration

    Swift

    func CTRunDelegateCreate(_ callbacks: UnsafePointer<CTRunDelegateCallbacks>, _ refCon: UnsafeMutablePointer<Void>) -> CTRunDelegate!

    Objective-C

    CTRunDelegateRef CTRunDelegateCreate ( const CTRunDelegateCallbacks *callbacks, void *refCon );

    Parameters

    callbacks

    A structure holding pointers to the callbacks for this run delegate.

    refCon

    A constant value associated with the run delegate to identify it.

    Return Value

    If successful, a reference to an immutable CTRunDelegate object. Otherwise, returns NULL.

    Discussion

    The run-delegate object can be used for reserving space in a line or for eliding the glyphs for a range of text altogether.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Returns a run delegate’s “refCon” value.

    Declaration

    Swift

    func CTRunDelegateGetRefCon(_ runDelegate: CTRunDelegate!) -> UnsafeMutablePointer<Void>

    Objective-C

    void * CTRunDelegateGetRefCon ( CTRunDelegateRef runDelegate );

    Parameters

    runDelegate

    The run delegate object being queried.

    Return Value

    A constant value associated with the run delegate as an identifier.

    Discussion

    The run delegate object was created with the returned “refCon” value.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Returns the type of CTRunDelegate objects.

    Declaration

    Swift

    func CTRunDelegateGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CTRunDelegateGetTypeID ( void );

    Discussion

    The return type is a Core Foundation type (CTType).

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

Callbacks

  • Defines a pointer to a function that determines typographic ascent of glyphs in the run.

    Declaration

    Objective-C

    typedef CGFloat (*CTRunDelegateGetAscentCallback) ( void* refCon );

    Parameters

    refCon

    The reference-constant value supplied to the CTRunDelegateCreate function when the run delegate was created.

    Return Value

    The typographic ascent of glyphs in the run associated with the run delegate.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Defines a pointer to a function that determines typographic descent of glyphs in the run.

    Declaration

    Objective-C

    typedef CGFloat (*CTRunDelegateGetDescentCallback) ( void* refCon );

    Parameters

    refCon

    The reference-constant value supplied to the CTRunDelegateCreate function when the run delegate was created.

    Return Value

    The typographic descent of glyphs in the run associated with the run delegate.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Defines a pointer to a function that determines the typographic width of glyphs in the run.

    Declaration

    Objective-C

    typedef CGFloat (*CTRunDelegateGetWidthCallback) ( void* refCon );

    Parameters

    refCon

    The reference-constant value supplied to the CTRunDelegateCreate function when the run delegate was created.

    Return Value

    The typographic width of glyphs in the run associated with the run delegate. A value of 0.0 indicates that the glyphs should not be drawn.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Defines a pointer to a function that is invoked when a CTRunDelegate object is deallocated.

    Declaration

    Objective-C

    typedef void (*CTRunDelegateDeallocateCallback) ( void* refCon );

    Parameters

    refCon

    The reference-constant value supplied to the CTRunDelegateCreate function when the run delegate was created.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

Data Types

  • A structure holding pointers to callbacks implemented by the run delegate.

    Declaration

    Swift

    struct CTRunDelegateCallbacks { var version: CFIndex var dealloc: CTRunDelegateDeallocateCallback var getAscent: CTRunDelegateGetAscentCallback var getDescent: CTRunDelegateGetDescentCallback var getWidth: CTRunDelegateGetWidthCallback }

    Objective-C

    typedef struct { CFIndex version; CTRunDelegateDeallocateCallback dealloc; CTRunDelegateGetAscentCallback getAscent; CTRunDelegateGetDescentCallback getDescent; CTRunDelegateGetWidthCallback getWidth; } CTRunDelegateCallbacks;

    Fields

    version

    The version number of the callbacks being passed in as a parameter to CTRunDelegateCreate. The initial version is kCTRunDelegateVersion1.

    dealloc

    The callback invoked when the retain count of a CTRunDelegate reaches 0 and the CTRunDelegate is deallocated. This callback may be NULL.

    getAscent

    The callback invoked to request the run delegate to determine and return the typographic ascent of glyphs in the run. This callback may be NULL, which is equivalent to a getAscent callback that always returns 0.

    getDescent

    The callback invoked to request the run delegate to determine and return the typographic descent of glyphs in the run. This callback may be NULL, which is equivalent to a getDescent callback that always returns 0.

    getWidth

    The callback invoked to request the run delegate to determine and return the typographic width of glyphs in the run. This callback may be NULL, which is equivalent to a getWidth callback that always returns 0.

    Discussion

    You pass in a pointer to this structure when you create a CTRunDelegate object with the CTRunDelegateCreate function. The callbacks defined in this structure are provided by the owner of a run delegate and are used to modify glyph metrics during layout. The values returned by the delegate are applied to each glyph in the run or runs corresponding to the attribute containing that delegate.

    See Callbacks for a discussion of the function-pointer types associated with these callbacks.

    Availability

    Available in iOS 3.2 and later.

  • The type of the CTRunDelegate opaque object.

    Declaration

    Swift

    typealias CTRunDelegateRef = CTRunDelegate

    Objective-C

    typedef const struct __CTRunDelegate * CTRunDelegateRef;

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

Constants

  • The version of the run delegate.

    Declaration

    Swift

    var kCTRunDelegateVersion1: Int { get } var kCTRunDelegateCurrentVersion: Int { get }

    Objective-C

    enum { kCTRunDelegateVersion1 = 1, kCTRunDelegateCurrentVersion = kCTRunDelegateVersion0 };

    Constants

    • kCTRunDelegateVersion1

      kCTRunDelegateVersion1

      Version 1 of the run delegate.

      Available in iOS 3.2 and later.

    • kCTRunDelegateCurrentVersion

      kCTRunDelegateCurrentVersion

      The current version of the run delegate.

      Available in iOS 3.2 and later.

    Discussion

    Set the version field of the CTRunDelegateCallbacks structure to kCTRunDelegateCurrentVersion when creating a CTRunDelegate object with a call to CTRunDelegateCreate.

    Import Statement