iOS Developer Library

Developer

ApplicationServices Framework Reference CTLine Reference

Options
Deployment Target:

On This Page
Language:

CTLine Reference

The CTLine opaque type represents a line of text.

A CTLine object contains an array of glyph runs. Line objects are created by the typesetter during a framesetting operation and can draw themselves directly into a graphics context.

Functions

  • Creates a single immutable line object directly from an attributed string.

    Declaration

    Swift

    func CTLineCreateWithAttributedString(_ string: CFAttributedString!) -> CTLine!

    Objective-C

    CTLineRef CTLineCreateWithAttributedString ( CFAttributedStringRef string );

    Parameters

    string

    The string from which the line is created.

    Return Value

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

    Discussion

    This function allows clients who need very simple line generation to create a line without creating a typesetter object. The typesetting is done under the hood. Without a typesetter object, the line cannot be properly broken. However, for simple things like text labels, line breaking is not an issue.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Creates a truncated line from an existing line.

    Declaration

    Swift

    func CTLineCreateTruncatedLine(_ line: CTLine!, _ width: Double, _ truncationType: CTLineTruncationType, _ truncationToken: CTLine!) -> CTLine!

    Objective-C

    CTLineRef CTLineCreateTruncatedLine ( CTLineRef line, double width, CTLineTruncationType truncationType, CTLineRef truncationToken );

    Parameters

    line

    The line from which to create a truncated line.

    width

    The width at which truncation begins. The line is truncated if its width is greater than the width passed in this parameter.

    truncationType

    The type of truncation to perform if needed. See CTLineTruncationType for possible values.

    truncationToken

    This token is added at the point where truncation took place, to indicate that the line was truncated. Usually, the truncation token is the ellipsis character (U+2026). If this parameter is set to NULL, then no truncation token is used and the line is simply cut off.

    Return Value

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

    Discussion

    The line specified in truncationToken should have a width less than the width specified by the width parameter. If the width of the line specified in truncationToken is greater than width and truncation is needed, the function returns NULL.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Creates a justified line from an existing line.

    Declaration

    Swift

    func CTLineCreateJustifiedLine(_ line: CTLine!, _ justificationFactor: CGFloat, _ justificationWidth: Double) -> CTLine!

    Objective-C

    CTLineRef CTLineCreateJustifiedLine ( CTLineRef line, CGFloat justificationFactor, double justificationWidth );

    Parameters

    line

    The line from which to create a justified line.

    justificationFactor

    Full or partial justification. When set to 1.0 or greater, full justification is performed. If this parameter is set to less than 1.0, varying degrees of partial justification are performed. If it is set to 0 or less, no justification is performed.

    justificationWidth

    The width to which the resultant line is justified. If justificationWidth is less than the actual width of the line, then negative justification is performed (that is, glyphs are squeezed together).

    Return Value

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

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Draws a complete line.

    Declaration

    Swift

    func CTLineDraw(_ line: CTLine!, _ context: CGContext!)

    Objective-C

    void CTLineDraw ( CTLineRef line, CGContextRef context );

    Parameters

    line

    The line to draw.

    context

    The context into which the line is drawn.

    Discussion

    This is a convenience function because the line could be drawn run-by-run by getting the glyph runs, getting the glyphs out of them, and calling a function such as CGContextShowGlyphsAtPositions. This call can leave the graphics context in any state and does not flush the context after the draw operation.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Returns the total glyph count for the line object.

    Declaration

    Swift

    func CTLineGetGlyphCount(_ line: CTLine!) -> CFIndex

    Objective-C

    CFIndex CTLineGetGlyphCount ( CTLineRef line );

    Parameters

    line

    The line whose glyph count is returned.

    Return Value

    The total glyph count for the line passed in.

    Discussion

    The total glyph count is equal to the sum of all of the glyphs in the glyph runs forming the line.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Returns the array of glyph runs that make up the line object.

    Declaration

    Swift

    func CTLineGetGlyphRuns(_ line: CTLine!) -> CFArray!

    Objective-C

    CFArrayRef CTLineGetGlyphRuns ( CTLineRef line );

    Parameters

    line

    The line whose glyph run array is returned.

    Return Value

    A CFArrayRef containing the CTRun objects that make up the line.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Gets the range of characters that originally spawned the glyphs in the line.

    Declaration

    Swift

    func CTLineGetStringRange(_ line: CTLine!) -> CFRange

    Objective-C

    CFRange CTLineGetStringRange ( CTLineRef line );

    Parameters

    line

    The line from which to obtain the string range.

    Return Value

    A CFRange structure that contains the range over the backing store string that spawned the glyphs, or if the function fails for any reason, an empty range.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Gets the pen offset required to draw flush text.

    Declaration

    Swift

    func CTLineGetPenOffsetForFlush(_ line: CTLine!, _ flushFactor: CGFloat, _ flushWidth: Double) -> Double

    Objective-C

    double CTLineGetPenOffsetForFlush ( CTLineRef line, CGFloat flushFactor, double flushWidth );

    Parameters

    line

    The line from which to obtain a flush position.

    flushFactor

    Determines the type of flushness. A flushFactor of 0 or less indicates left flush. A flushFactor of 1.0 or more indicates right flush. Flush factors between 0 and 1.0 indicate varying degrees of center flush, with a value of 0.5 being totally center flush.

    flushWidth

    Specifies the width to which the flushness operation should apply.

    Return Value

    The offset from the current pen position for the flush operation.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Calculates the image bounds for a line.

    Declaration

    Swift

    func CTLineGetImageBounds(_ line: CTLine!, _ context: CGContext!) -> CGRect

    Objective-C

    CGRect CTLineGetImageBounds ( CTLineRef line, CGContextRef context );

    Parameters

    line

    The line whose image bounds are calculated.

    context

    The context for which the image bounds are calculated. This is required because the context could have settings in it that would cause changes in the image bounds.

    Return Value

    A rectangle that tightly encloses the paths of the line's glyphs, or, if the line or context is invalid, CGRectNull.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Calculates the typographic bounds of a line.

    Declaration

    Swift

    func CTLineGetTypographicBounds(_ line: CTLine!, _ ascent: UnsafeMutablePointer<CGFloat>, _ descent: UnsafeMutablePointer<CGFloat>, _ leading: UnsafeMutablePointer<CGFloat>) -> Double

    Objective-C

    double CTLineGetTypographicBounds ( CTLineRef line, CGFloat *ascent, CGFloat *descent, CGFloat *leading );

    Parameters

    line

    The line whose typographic bounds are calculated.

    ascent

    On output, the ascent of the line. This parameter can be set to NULL if not needed.

    descent

    On output, the descent of the line. This parameter can be set to NULL if not needed.

    leading

    On output, the leading of the line. This parameter can be set to NULL if not needed.

    Return Value

    The typographic width of the line. If the line is invalid, this function returns 0.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Returns the trailing whitespace width for a line.

    Declaration

    Swift

    func CTLineGetTrailingWhitespaceWidth(_ line: CTLine!) -> Double

    Objective-C

    double CTLineGetTrailingWhitespaceWidth ( CTLineRef line );

    Parameters

    line

    The line whose trailing whitespace width is calculated.

    Return Value

    The width of the line's trailing whitespace. If the line is invalid, this function will always return zero.

    Discussion

    Creating a line for a width can result in a line that is actually longer than the desired width due to trailing whitespace. Although this is typically not an issue due to whitespace being invisible, this function can be used to determine what amount of a line's width is due to trailing whitespace.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Performs hit testing.

    Declaration

    Swift

    func CTLineGetStringIndexForPosition(_ line: CTLine!, _ position: CGPoint) -> CFIndex

    Objective-C

    CFIndex CTLineGetStringIndexForPosition ( CTLineRef line, CGPoint position );

    Parameters

    line

    The line being examined.

    position

    The location of the mouse click relative to the line's origin.

    Return Value

    The string index for the position, or if the line does not support string access, kCFNotFound. Relative to the line's string range, this value can be no less than the first string index and no greater than the last string index plus 1.

    Discussion

    This function can be used to determine the string index for a mouse click or other event. This string index corresponds to the character before which the next character should be inserted. This determination is made by analyzing the string from which a typesetter was created and the corresponding glyphs as embodied by a particular line.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Determines the graphical offset or offsets for a string index.

    Declaration

    Swift

    func CTLineGetOffsetForStringIndex(_ line: CTLine!, _ charIndex: CFIndex, _ secondaryOffset: UnsafeMutablePointer<CGFloat>) -> CGFloat

    Objective-C

    CGFloat CTLineGetOffsetForStringIndex ( CTLineRef line, CFIndex charIndex, CGFloat *secondaryOffset );

    Parameters

    line

    The line from which the offset is requested.

    charIndex

    The string index corresponding to the desired position.

    secondaryOffset

    On output, the secondary offset along the baseline for charIndex. When a single caret is sufficient for a string index, this value will be the same as the primary offset, which is the return value of this function. May be NULL.

    Return Value

    The primary offset along the baseline for charIndex, or 0.0 if the line does not support string access.

    Discussion

    This function returns the graphical offset or offsets corresponding to a string index, suitable for movement between adjacent lines or for drawing a custom caret. For moving between adjacent lines, the primary offset can be adjusted for any relative indentation of the two lines; a CGPoint constructed with the adjusted offset for its x value and 0.0 for its y value is suitable for passing to CTLineGetStringIndexForPosition. For drawing a custom caret, the returned primary offset corresponds to the portion of the caret that represents the visual insertion location for a character whose direction matches the line's writing direction.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

  • Returns the Core Foundation type identifier of the line object.

    Declaration

    Swift

    func CTLineGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CTLineGetTypeID ( void );

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.

Data Types

  • A reference to a line object.

    Declaration

    Swift

    typealias CTLineRef = CTLine

    Objective-C

    typedef const struct __CTLine *CTLineRef;

    Availability

    Available in iOS 3.2 and later.

Constants

  • Truncation types required by the CTLineCreateTruncatedLine function to tell the truncation engine which type of truncation is being requested.

    Declaration

    Swift

    enum CTLineTruncationType : UInt32 { case Start case End case Middle }

    Objective-C

    enum{ kCTLineTruncationStart = 0, kCTLineTruncationEnd = 1, kCTLineTruncationMiddle = 2 }; typedef uint32_t CTLineTruncationType;

    Constants

    • Start

      kCTLineTruncationStart

      Truncate the beginning of the line, leaving the end portion visible.

      Available in iOS 3.2 and later.

    • End

      kCTLineTruncationEnd

      Truncate the end of the line, leaving the start portion visible.

      Available in iOS 3.2 and later.

    • Middle

      kCTLineTruncationMiddle

      Truncate the middle of the line, leaving both the start and the end portions visible.

      Available in iOS 3.2 and later.

    Import Statement

    import CoreText

    Availability

    Available in iOS 3.2 and later.