iOS Developer Library

Developer

ApplicationServices Framework Reference CTFrame Reference

Options
Deployment Target:

On This Page
Language:

CTFrame Reference

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

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

    Declaration

    Swift

    func CTFrameGetStringRange(_ frame: CTFrame!) -> CFRange

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    func CTFrameGetVisibleStringRange(_ frame: CTFrame!) -> CFRange

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Returns the path used to create the frame.

    Declaration

    Swift

    func CTFrameGetPath(_ frame: CTFrame!) -> CGPath!

    Objective-C

    CGPathRef CTFrameGetPath ( CTFrameRef frame );

    Parameters

    frame

    The frame whose path is returned.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Returns the frame attributes used to create the frame.

    Declaration

    Swift

    func CTFrameGetFrameAttributes(_ frame: CTFrame!) -> CFDictionary!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Returns an array of lines stored in the frame.

    Declaration

    Swift

    func CTFrameGetLines(_ frame: CTFrame!) -> CFArray!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Copies a range of line origins for a frame.

    Declaration

    Swift

    func CTFrameGetLineOrigins(_ frame: CTFrame!, _ range: CFRange, _ origins: UnsafeMutablePointer<CGPoint>)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Draws an entire frame into a context.

    Declaration

    Swift

    func CTFrameDraw(_ frame: CTFrame!, _ context: CGContext!)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Returns the type identifier for the CTFrame opaque type.

    Declaration

    Swift

    func CTFrameGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CTFrameGetTypeID ( void );

    Return Value

    The type identifier for the CTFrame opaque type.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in iOS 3.2 and later.

Data Types

  • A reference to a Core text frame object.

    Declaration

    Swift

    typealias CTFrameRef = CTFrame

    Objective-C

    typedef const struct __CTFrame *CTFrameRef;

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    enum CTFramePathFillRule : UInt32 { case EvenOdd case WindingNumber }

    Objective-C

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

    Discussion

    For descriptions of the constants, see CTFramePathFillRule Constants.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in iOS 4.2 and later.

Constants

  • These constants specify frame progression types.

    Declaration

    Swift

    enum CTFrameProgression : UInt32 { case TopToBottom case RightToLeft case LeftToRight }

    Objective-C

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

    Constants

    • TopToBottom

      kCTFrameProgressionTopToBottom

      Lines are stacked top to bottom for horizontal text.

      Available in iOS 3.2 and later.

    • RightToLeft

      kCTFrameProgressionRightToLeft

      Lines are stacked right to left for vertical text.

      Available in iOS 3.2 and later.

    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.

    Import Statement

    Objective-C

    @import CoreText;

    Swift

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • These constants specify the fill rule used by a frame

    Declaration

    Swift

    enum CTFramePathFillRule : UInt32 { case EvenOdd case WindingNumber }

    Objective-C

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

    Constants

    • EvenOdd

      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.

    • WindingNumber

      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.

    Discussion

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

  • Specifies progression for a frame.

    Declaration

    Swift

    let kCTFrameProgressionAttributeName: CFString!

    Objective-C

    const CFStringRef kCTFrameProgressionAttributeName;

    Constants

    • kCTFrameProgressionAttributeName

      kCTFrameProgressionAttributeName

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

      Available in iOS 3.2 and later.

    Discussion

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

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

    Declaration

    Swift

    let kCTFramePathFillRuleAttributeName: CFString!

    Objective-C

    extern const CFStringRef kCTFramePathFillRuleAttributeName;

    Constants

  • The key used to specify the frame width.

    Declaration

    Swift

    let kCTFramePathWidthAttributeName: CFString!

    Objective-C

    extern const CFStringRef kCTFramePathWidthAttributeName;

    Constants

    • kCTFramePathWidthAttributeName

      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.

  • Specifies array of paths to clip frame.

    Declaration

    Swift

    let kCTFrameClippingPathsAttributeName: CFString!

    Objective-C

    extern const CFStringRef kCTFrameClippingPathsAttributeName CT_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_4_3);

    Constants

    • kCTFrameClippingPathsAttributeName

      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.

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

    Declaration

    Swift

    let kCTFramePathClippingPathAttributeName: CFString!

    Objective-C

    extern const CFStringRef kCTFramePathClippingPathAttributeName CT_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_4_3);

    Constants

    • kCTFramePathClippingPathAttributeName

      kCTFramePathClippingPathAttributeName

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

      Available in iOS 4.3 and later.