CTRunDelegate Reference

Derived from
CFType
Framework
CoreText
Declared in
CTRunDelegate.h

Overview

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 by Task

Creating a Run Delegate

Getting Information About a Run Delegate

Functions

CTRunDelegateCreate

Creates an immutable instance of a run delegate.

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.

Availability
  • Available in iOS 3.2 and later.
Declared In
CTRunDelegate.h

CTRunDelegateGetRefCon

Returns a run delegate’s “refCon” value.

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.

Availability
  • Available in iOS 3.2 and later.
Declared In
CTRunDelegate.h

CTRunDelegateGetTypeID

Returns the type of CTRunDelegate objects.

CFTypeID CTRunDelegateGetTypeID( void );
Discussion

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

Availability
  • Available in iOS 3.2 and later.
Declared In
CTRunDelegate.h

Callbacks by Task

Determining Typographic Traits

Deallocating the Run Delegate

Callbacks

CTRunDelegateDeallocateCallback

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

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

You would declare the deallocation function like this if you were to name it MyDeallocationCallback:

void MyDeallocationCallback( void* refCon );

Parameters
refCon

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

Availability
  • Available in iOS 3.2 and later.
Declared In
CTRunDelegate.h

CTRunDelegateGetAscentCallback

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

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

You would declare the get-ascent function like this if you were to name it MyGetAscentCallback:

CGFloat MyGetAscentCallback( 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.

Availability
  • Available in iOS 3.2 and later.
Declared In
CTRunDelegate.h

CTRunDelegateGetDescentCallback

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

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

You would declare the get-descent function like this if you were to name it MyGetDescentCallback:

CGFloat MyGetDescentCallback( 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.

Availability
  • Available in iOS 3.2 and later.
Declared In
CTRunDelegate.h

CTRunDelegateGetWidthCallback

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

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

You would declare the get-width function like this if you were to name it MyGetWidthCallback:

CGFloat MyGetWidthCallback( 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.

Availability
  • Available in iOS 3.2 and later.
Declared In
CTRunDelegate.h

Data Types

CTRunDelegateCallbacks

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

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.
Declared In
CTRunDelegate.h

CTRunDelegateRef

The type of the CTRunDelegate opaque object.

typedef const struct __CTRunDelegate * CTRunDelegateRef;
Availability
  • Available in iOS 3.2 and later.
Declared In
CTRunDelegate.h

Constants

Run Delegate Versions

The version of the run delegate.

enum {
   kCTRunDelegateVersion1 = 1,
   kCTRunDelegateCurrentVersion = kCTRunDelegateVersion0
};
Constants
kCTRunDelegateVersion1

Version 1 of the run delegate.

Available in iOS 3.2 and later.

Declared in CTRunDelegate.h.

kCTRunDelegateCurrentVersion

The current version of the run delegate.

Available in iOS 3.2 and later.

Declared in CTRunDelegate.h.

Discussion

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

Declared In
CTRunDelegate.h