CTRun Reference

Derived from
CFType
Framework
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