CTLine Reference
| Derived from | CFType |
| Framework | ApplicationServices/CoreText |
| Declared in | CTLine.h |
Overview
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 by Task
Creating Lines
Drawing the Line
Getting Line Data
Measuring Lines
Getting Line Positioning
Getting the Type Identifier
Functions
CTLineCreateJustifiedLine
Creates a justified line from an existing line.
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.0or greater, full justification is performed. If this parameter is set to less than1.0, varying degrees of partial justification are performed. If it is set to0or 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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineCreateTruncatedLine
Creates a truncated line from an existing line.
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 toNULL, 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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineCreateWithAttributedString
Creates a single immutable line object directly from an attributed string.
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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineDraw
Draws a complete line.
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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineGetGlyphCount
Returns the total glyph count for the line object.
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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineGetGlyphRuns
Returns the array of glyph runs that make up the line object.
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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineGetImageBounds
Calculates the image bounds for a line.
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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineGetOffsetForStringIndex
Determines the graphical offset or offsets for a string index.
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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineGetPenOffsetForFlush
Gets the pen offset required to draw flush text.
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
0or less indicates left flush. A flushFactor of1.0or more indicates right flush. Flush factors between0and1.0indicate varying degrees of center flush, with a value of0.5being 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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineGetStringIndexForPosition
Performs hit testing.
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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineGetStringRange
Gets the range of characters that originally spawned the glyphs in the line.
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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineGetTrailingWhitespaceWidth
Returns the trailing whitespace width for a line.
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.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineGetTypeID
Returns the Core Foundation type identifier of the line object.
CFTypeID CTLineGetTypeID( void );
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hCTLineGetTypographicBounds
Calculates the typographic bounds of a line.
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
NULLif not needed.- descent
On output, the descent of the line. This parameter can be set to
NULLif not needed.- leading
On output, the leading of the line. This parameter can be set to
NULLif not needed.
Return Value
The typographic width of the line. If the line is invalid, this function returns 0.
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hData Types
CTLineRef
A reference to a line object.
typedef const struct __CTLine *CTLineRef;
Availability
- Available in iOS 3.2 and later.
Declared In
CTLine.hConstants
CTLineTruncationType
Truncation types required by the CTLineCreateTruncatedLine function to tell the truncation engine which type of truncation is being requested.
enum{
kCTLineTruncationStart = 0,
kCTLineTruncationEnd = 1,
kCTLineTruncationMiddle = 2
};
typedef uint32_t CTLineTruncationType;
Constants
kCTLineTruncationStartTruncate the beginning of the line, leaving the end portion visible.
Available in iOS 3.2 and later.
Declared in
CTLine.h.kCTLineTruncationEndTruncate the end of the line, leaving the start portion visible.
Available in iOS 3.2 and later.
Declared in
CTLine.h.kCTLineTruncationMiddleTruncate the middle of the line, leaving both the start and the end portions visible.
Available in iOS 3.2 and later.
Declared in
CTLine.h.
Declared In
CTLine.h© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-02-25)