CTTypesetter Reference

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

Overview

The CTTypesetter opaque type represents a typesetter, which performs line layout.

Line layout includes word wrapping, hyphenation, and line breaking in either vertical or horizontal rectangles. A typesetter object takes as input an attributed string and produces a line of typeset glyphs (composed into glyph runs) in a CTLine object. The typesetter performs character-to-glyph encoding, glyph ordering, and positional operations, such as kerning, tracking, and baseline adjustments. If multiline layout is needed, it is performed by a framesetter object, which calls into the typesetter to generate the typeset lines to fill the frame.

A framesetter encapsulates a typesetter and provides a reference to it as a convenience, but a caller may also choose to create a freestanding typesetter.

Functions by Task

Creating a Typesetter

Creating Lines

Breaking Lines

Getting the Type Identifier

Functions

CTTypesetterCreateLine

Creates an immutable line from the typesetter.

CTLineRef CTTypesetterCreateLine( CTTypesetterRef typesetter, CFRange stringRange );
Parameters
typesetter

The typesetter that creates the line. This parameter is required and cannot be set to NULL.

stringRange

The string range on which the line is based. If the length portion of range is set to 0, then the typesetter continues to add glyphs to the line until it runs out of characters in the string. The location and length of the range must be within the bounds of the string, or the call will fail.

Return Value

A reference to a CTLine object if the call was successful; otherwise, NULL.

Discussion

The resultant line consists of glyphs in the correct visual order, ready to draw. This function is equivalent to CTTypesetterCreateLineWithOffset with an offset of 0.0.

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

CTTypesetterCreateLineWithOffset

Creates an immutable line from the typesetter at a specified line offset.

CTLineRef CTTypesetterCreateLineWithOffset(CTTypesetterRef typesetter, CFRange stringRange, double offset);
Parameters
typesetter

The typesetter that creates the line. This parameter is required and cannot be set to NULL.

stringRange

The string range on which the line is based. If the length portion of range is set to 0, then the typesetter continues to add glyphs to the line until it runs out of characters in the string. The location and length of the range must be within the bounds of the string, or the call will fail.

offset

The line position offset.

Return Value

A reference to a CTLine object if the call was successful; otherwise, NULL.

Discussion

The resultant line consists of glyphs in the correct visual order, ready to draw.

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

CTTypesetterCreateWithAttributedString

Creates an immutable typesetter object using an attributed string.

CTTypesetterRef CTTypesetterCreateWithAttributedString( CFAttributedStringRef string );
Parameters
string

The attributed string to typeset. This parameter must be filled in with a valid CFAttributedString object.

Return Value

A reference to a CTTypesetter object if the call was successful; otherwise, NULL.

Discussion

The resultant typesetter can be used to create lines, perform line breaking, and do other contextual analysis based on the characters in the string.

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

CTTypesetterCreateWithAttributedStringAndOptions

Creates an immutable typesetter object using an attributed string and a dictionary of options.

CTTypesetterRef CTTypesetterCreateWithAttributedStringAndOptions( CFAttributedStringRef string, CFDictionaryRef options );
Parameters
string

The attributed string to typeset. This parameter must be filled in with a valid CFAttributedString object.

options

A dictionary of typesetter options, or NULL if there are none.

Return Value

A reference to a CTTypesetter object if the call was successful; otherwise, NULL.

Discussion

The resultant typesetter can be used to create lines, perform line breaking, and do other contextual analysis based on the characters in the string.

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

CTTypesetterGetTypeID

Returns the Core Foundation type identifier of the typesetter object.

CFTypeID CTTypesetterGetTypeID( void );
Availability
  • Available in iOS 3.2 and later.
Declared In
CTTypesetter.h

CTTypesetterSuggestClusterBreak

Suggests a cluster line breakpoint based on the width provided.

CFIndex CTTypesetterSuggestClusterBreak( CTTypesetterRef typesetter, CFIndex startIndex, double width );
Parameters
typesetter

The typesetter that creates the line. This parameter is required and cannot be set to NULL.

startIndex

The starting point for the typographic cluster-break calculations. The break calculations include the character starting at startIndex.

width

The requested typographic cluster-break width.

Return Value

A count of the characters from startIndex that would cause the cluster break. The value returned can be used to construct a character range for CTTypesetterCreateLine.

Discussion

This cluster break is similar to a character break, except that it does not break apart linguistic clusters. No other contextual analysis is done. This can be used by the caller to implement a different line-breaking scheme, such as hyphenation. A typographic cluster break can also be triggered by a hard-break character in the stream. This function is equivalent to CTTypesetterSuggestClusterBreakWithOffset with an offset of 0.0.

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

CTTypesetterSuggestClusterBreakWithOffset

Suggests a cluster line breakpoint based on the specified width and line offset.

CFIndex CTTypesetterSuggestClusterBreakWithOffset( CTTypesetterRef typesetter, CFIndex startIndex, double width, double offset);
Parameters
typesetter

The typesetter that creates the line. This parameter is required and cannot be set to NULL.

startIndex

The starting point for the typographic cluster-break calculations. The break calculations include the character starting at startIndex.

width

The requested typographic cluster-break width.

offset

The line offset position.

Return Value

A count of the characters from startIndex that would cause the cluster break. The value returned can be used to construct a character range for CTTypesetterCreateLine.

Discussion

This cluster break is similar to a character break, except that it does not break apart linguistic clusters. No other contextual analysis is done. This can be used by the caller to implement a different line-breaking scheme, such as hyphenation. A typographic cluster break can also be triggered by a hard-break character in the stream.

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

CTTypesetterSuggestLineBreak

Suggests a contextual line breakpoint based on the width provided.

CFIndex CTTypesetterSuggestLineBreak( CTTypesetterRef typesetter, CFIndex startIndex, double width );
Parameters
typesetter

The typesetter that creates the line. This parameter is required and cannot be set to NULL.

startIndex

The starting point for the line-break calculations. The break calculations include the character starting at startIndex.

width

The requested line-break width.

Return Value

A count of the characters from startIndex that would cause the line break. The value returned can be used to construct a character range for CTTypesetterCreateLine.

Discussion

The line break can be triggered either by a hard-break character in the stream or by filling the specified width with characters. This function is equivalent to CTTypesetterSuggestLineBreakWithOffset with an offset of 0.0.

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

CTTypesetterSuggestLineBreakWithOffset

Suggests a contextual line breakpoint based on the width provided and the specified offset.

CFIndex CTTypesetterSuggestLineBreakWithOffset(CTTypesetterRef typesetter, CFIndex startIndex, double width, double offset);
Parameters
typesetter

The typesetter that creates the line. This parameter is required and cannot be set to NULL.

startIndex

The starting point for the line-break calculations. The break calculations include the character starting at startIndex.

width

The requested line-break width.

offset

The line position offset.

Return Value

A count of the characters from startIndex and offset that would cause the line break. The value returned can be used to construct a character range for CTTypesetterCreateLine.

Discussion

The line break can be triggered either by a hard-break character in the stream or by filling the specified width with characters.

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

Data Types

CTTypesetterRef

A reference to a typesetter object.

typedef const struct __CTTypesetter *CTTypesetterRef;
Availability
  • Available in iOS 3.2 and later.
Declared In
CTTypesetter.h

Constants

Typesetter Options

These constants control aspects of the typesetter’s bidirectional text processing.

const CFStringRef kCTTypesetterOptionDisableBidiProcessing;
const CFStringRef kCTTypesetterOptionForcedEmbeddingLevel;
Constants
kCTTypesetterOptionDisableBidiProcessing

Disables bidirectional processing. Value must be a CFBoolean object. Default value is false. Normally, typesetting applies the Unicode Bidirectional Algorithm as described in Unicode Standard Annex #9. If a typesetter is created with this option set to true, no directional reordering is performed, and any directional control characters are ignored.

Available in iOS 3.2 and later.

Deprecated in iOS 6.0.

Declared in CTTypesetter.h.

kCTTypesetterOptionForcedEmbeddingLevel

Specifies the embedding level. Value must be a CFNumberRef object. Default is unset. Normally, typesetting applies the Unicode Bidirectional Algorithm as described in Unicode Standard Annex #9. If present, this option specifies the embedding level, and any directional control characters are ignored.

Available in iOS 3.2 and later.

Declared in CTTypesetter.h.



© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-02-25)

Did this document help you? Yes It's good, but... Not helpful...