CTFrame Reference

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

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

Getting Lines

Drawing the Frame

Getting the Type Identifier

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

Related Sample Code

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 iOS 3.2 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. Each CGPoint in this array is the origin of the corresponding line in the array of lines returned by CTFrameGetLines relative to the origin of the path's bounding box, which can be obtained from CGPathGetPathBoundingBox.

Discussion

This function copies a range of CGPoint structures into the origins buffer. The maximum number of line origins this function will copy into the origins buffer is the count of the array of lines (the length of the range parameter).

Special Considerations

In versions of OS X prior to 10.7 and versions of iOS prior to 4.2, this function may function unpredictably if the frame is not rectangular.

Availability

Available in iOS 3.2 and later.

Related Sample Code

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

Related Sample Code

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

Related Sample Code

CoreTextPageViewer

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

Related Sample Code

CoreTextPageViewer

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

Related Sample Code

CoreTextPageViewer

Declared In

CTFrame.h

Data Types

CTFrameRef

A reference to a Core text frame object.

typedef const struct __CTFrame *CTFrameRef;

Availability

Available in iOS 3.2 and later.

Declared In

CTFrame.h

CTFramePathFillRule

The type for constants that specify a fill rule used by a frame.

enum
{
   kCTFramePathFillEvenOdd = 0,
   kCTFramePathFillWindingNumber = 1
};
typedef uint32_t CTFramePathFillRule;

Discussion

For descriptions of the constants, see “CTFramePathFillRule Constants.”

Availability

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

Declared in CTFrame.h.

kCTFrameProgressionRightToLeft

Lines are stacked right to left for vertical text.

Available in iOS 3.2 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

CTFramePathFillRule Constants

These constants specify the fill rule used by a frame

enum
{
   kCTFramePathFillEvenOdd = 0,
   kCTFramePathFillWindingNumber = 1
};
typedef uint32_t CTFramePathFillRule;

Constants

kCTFramePathFillEvenOdd

Text is filled in the area that would be painted if the path were given to CGContextEOFillPath.

Available in iOS 4.2 and later.

Declared in CTFrame.h.

kCTFramePathFillWindingNumber

Text is fill in the area that would be painted if the path were given to CGContextFillPath.

Available in iOS 4.2 and later.

Declared in CTFrame.h.

Discussion

When a path intersects with itself, the client should specify which rule to use for deciding the area of the path.

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 iOS 3.2 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

kCTFramePathFillRuleAttributeName

The key used to specify the fill rule for a frame.

extern const CFStringRef kCTFramePathFillRuleAttributeName;

Constants

kCTFramePathFillRuleAttributeName

The value must be a CFNumberRef object containing a CTFramePathFillRule constant. See “CTFramePathFillRule Constants” for more information. The default value is kCTFramePathFillEvenOdd.

Available in iOS 4.2 and later.

Declared in CTFrame.h.

Declared In

CTFrame.h

kCTFramePathWidthAttributeName

The key used to specify the frame width.

extern const CFStringRef kCTFramePathWidthAttributeName;

Constants

kCTFramePathWidthAttributeName

The value must be a CFNumberRef object containing a value specifying the frame width. The default width value is zero.

Available in iOS 4.2 and later.

Declared in CTFrame.h.

kCTFrameClippingPathsAttributeName

Specifies array of paths to clip frame.

extern const CFStringRef kCTFrameClippingPathsAttributeName CT_AVAILABLE_STARTING( __MAC_10_7,
   __IPHONE_4_3);

Constants

kCTFrameClippingPathsAttributeName

The value must be a CFArrayRef containing CFDictionaryRefs. Each dictionary should have a kCTFramePathClippingPathAttributeName key-value pair, and can have a kCTFramePathFillRuleAttributeName key-value pair and kCTFramePathFillRuleAttributeName key-value pair as optional parameters.

Available in iOS 4.3 and later.

Declared in CTFrame.h.

kCTFramePathClippingPathAttributeName

Specifies clipping path. This attribute is valid only in a dictionary contained in an array specified by kCTFrameClippingPathsAttributeName.

extern const CFStringRef kCTFramePathClippingPathAttributeName CT_AVAILABLE_STARTING( __MAC_10_7,
   __IPHONE_4_3);

Constants

kCTFramePathClippingPathAttributeName

The value must be a CGPathRef specifying a clipping pat. See “kCTFrameClippingPathsAttributeName.”

Available in iOS 4.3 and later.

Declared in CTFrame.h.

Did this document help you?

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