CTRun Reference

Derived from	CFType
Framework	ApplicationServices/CoreText
Declared in	CTRun.h

Overview

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

Getting Glyph Run Data

Measuring the Glyph Run

Drawing the Glyph Run

Getting the Type Identifier

Functions

CTRunDraw

Draws a complete run or part of one.

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetAdvances

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

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetAdvancesPtr

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

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetAttributes

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

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetGlyphCount

Gets the glyph count for the run.

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetGlyphs

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

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetGlyphsPtr

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

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetImageBounds

Calculates the image bounds for a glyph range.

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetPositions

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

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetPositionsPtr

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

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetStatus

Returns the run's status.

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetStringIndices

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

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetStringIndicesPtr

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

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetStringRange

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

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetTextMatrix

Returns the text matrix needed to draw this run.

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetTypeID

Returns the Core Foundation type identifier of the run object.

CFTypeID CTRunGetTypeID (
   void
);

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

CTRunGetTypographicBounds

Gets the typographic bounds of the run.

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.

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

Data Types

CTRunRef

A reference to a run object.

typedef const struct __CTRun *CTRunRef;

Availability

Available in iOS 3.2 and later.

Declared In

CTRun.h

Constants

CTRunStatus

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

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

Constants

kCTRunStatusNoStatus

The run has no special attributes.

Available in iOS 3.2 and later.

Declared in CTRun.h.

kCTRunStatusRightToLeft

The run proceeds from right to left.

Available in iOS 3.2 and later.

Declared in CTRun.h.

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 iOS 3.2 and later.

Declared in CTRun.h.

kCTRunStatusHasNonIdentityMatrix

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

Available in iOS 3.2 and later.

Declared in CTRun.h.

Declared In

CTRun.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.