---

CTFrame Reference

Overview

The CTFrame opaque type represents a frame containing multiple lines of text. The frame object is the output resulting from the text-framing process performed by a framesetter object.

You can draw the entire text frame directly into the current graphic context. The frame object contains an array of line objects that can be retrieved for individual rendering or to get glyph information.

Functions by Task

Getting Frame Data

• CTFrameGetStringRange
• CTFrameGetVisibleStringRange
• CTFrameGetPath
• CTFrameGetFrameAttributes

Getting Lines

• CTFrameGetLines
• CTFrameGetLineOrigins

Drawing the Frame

• CTFrameDraw

Getting the Type Identifier

• CTFrameGetTypeID

Functions

CTFrameDraw

Draws an entire frame into a context.

void CTFrameDraw( CTFrameRef frame, CGContextRef context );

Parameters

frame

The frame to draw.

context

The context in which to draw the frame.

Discussion

If both the frame and the context are valid, the frame is drawn in the context. This call can leave the context in any state and does not flush it after the draw operation.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CTFrame.h

CTFrameGetFrameAttributes

Returns the frame attributes used to create the frame.

CFDictionaryRef CTFrameGetFrameAttributes( CTFrameRef frame );

Parameters

frame

The frame whose attributes are returned.

Return Value

A reference to a CFDictionary object containing the frame attributes that were used to create the frame, or, if the frame was created without any frame attributes, NULL.

Discussion

You can create a frame with an attributes dictionary to control various aspects of the framing process. These attributes are different from the ones used to create an attributed string.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CTFrame.h

CTFrameGetLineOrigins

Copies a range of line origins for a frame.

void CTFrameGetLineOrigins( CTFrameRef frame, CFRange range, CGPoint origins[] );

Parameters

frame

The frame whose line origin array is copied.

range

The range of line origins you wish to copy. If the length of the range is 0, then the copy operation continues from the start index of the range to the last line origin.

origins

The buffer to which the origins are copied. The buffer must have at least as many elements as specified by range's length.

Discussion

This function copies a range of CGPoint structures. Each CGPoint is the origin of the corresponding line in the array of lines returned by CTFrameGetLines, relative to the origin of the frame's path. The maximum number of line origins returned by this function is the count of the array of lines.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CTFrame.h

CTFrameGetLines

Returns an array of lines stored in the frame.

CFArrayRef CTFrameGetLines( CTFrameRef frame );

Parameters

frame

The frame whose line array is returned.

Return Value

A CFArray object containing the CTLine objects that make up the frame, or, if there are no lines in the frame, an array with no elements.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CTFrame.h

CTFrameGetPath

Returns the path used to create the frame.

CGPathRef CTFrameGetPath( CTFrameRef frame );

Parameters

frame

The frame whose path is returned.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CTFrame.h

CTFrameGetStringRange

Returns the range of characters originally requested to fill the frame.

CFRange CTFrameGetStringRange( CTFrameRef frame );

Parameters

frame

The frame whose character range is returned.

Return Value

A CFRange structure containing the backing store range of characters that were originally requested to fill the frame, or, if the function call is not successful, an empty range.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CTFrame.h

CTFrameGetTypeID

Returns the type identifier for the CTFrame opaque type.

CFTypeID CTFrameGetTypeID( void );

Return Value

The type identifier for the CTFrame opaque type.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CTFrame.h

CTFrameGetVisibleStringRange

Returns the range of characters that actually fit in the frame.

CFRange CTFrameGetVisibleStringRange( CTFrameRef frame );

Parameters

frame

The frame whose visible character range is returned.

Return Value

A CFRange structure containing the backing store range of characters that fit into the frame, or if the function call is not successful or no characters fit in the frame, an empty range.

Discussion

This function can be used to cascade frames, because it returns the range of characters that can be seen in the frame. The next frame would start where this frame ends.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CTFrame.h

Data Types

CTFrameRef

A reference to a Core text frame object.

typedef const struct __CTFrame *CTFrameRef;

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CTFrame.h

Constants

CTFrameProgression

These constants specify frame progression types.

enum{
   kCTFrameProgressionTopToBottom = 0,
   kCTFrameProgressionRightToLeft = 1
};
typedef uint32_t CTFrameProgression;

Constants

kCTFrameProgressionTopToBottom

Lines are stacked top to bottom for horizontal text.

Available in Mac OS X v10.5 and later.

Declared in CTFrame.h

kCTFrameProgressionRightToLeft

Lines are stacked right to left for vertical text.

Available in Mac OS X v10.5 and later.

Declared in CTFrame.h

Discussion

The lines of text within a frame may be stacked for either horizontal or vertical text. Values are enumerated for each stacking type supported by CTFrame. Frames created with a progression type specifying vertical text rotate lines 90 degrees counterclockwise when drawing.

Declared In

CTFrame.h

kCTFrameProgressionAttributeName

Specifies progression for a frame.

const CFStringRef kCTFrameProgressionAttributeName;

Constants

kCTFrameProgressionAttributeName

A CFNumberRef object containing a “CTFrameProgression” constant. The default is kCTFrameProgressionTopToBottom.

Available in Mac OS X v10.5 and later.

Declared in CTFrame.h

Discussion

This value determines the line-stacking behavior for a frame and does not affect the appearance of the glyphs within that frame.

Declared In

CTFrame.h

---