NSString UIKit Additions Reference

Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
NSText.h
UIStringDrawing.h

Overview

The UIKit framework adds methods to NSString to support the drawing of strings and to compute the bounding box of a string prior to drawing. None of these methods affects the contents of the string object itself, only how it is drawn on screen.

By default, strings are drawn using the native coordinate system of iOS, where content is drawn down and to the right from the specified origin point. Whenever you are positioning string content, you should keep this orientation in mind and use the upper-left corner of the string’s bounding box as the origin point for drawing.

The methods described in this class extension must be used from your app’s main thread.

Tasks

Computing Metrics for a Single Line of Text

Computing Metrics for Multiple Lines of Text

Drawing Strings on a Single Line

Drawing Strings in a Given Area

Instance Methods

drawAtPoint:forWidth:withFont:fontSize:lineBreakMode:baselineAdjustment:

Draws the string in a single line at the specified point in the current graphics context using the specified font and attributes.

- (CGSize)drawAtPoint:(CGPoint)point forWidth:(CGFloat)width withFont:(UIFont *)font fontSize:(CGFloat)fontSize lineBreakMode:(UILineBreakMode)lineBreakMode baselineAdjustment:(UIBaselineAdjustment)baselineAdjustment
Parameters
point

The location (in the coordinate system of the current graphics context) at which to draw the string. This point represents the top-left corner of the string’s bounding box.

width

The maximum width of the string.

font

The font to use for rendering.

fontSize

The font size to use instead of the one associated with the font object in the font parameter.

lineBreakMode

The line break options for computing the size of the string. For a list of possible values, see NSLineBreakMode.

baselineAdjustment

Specifies the vertical text-adjustment rule to use. This rule is used to determine the position of the text in cases where the text must be drawn at a smaller size.

Return Value

The size of the rendered string. The returned values may be rounded up to the nearest whole number.

Discussion

This method draws only a single line of text, drawing as much of the string as possible using the given font and constraints. This method does not perform any line wrapping during drawing.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIStringDrawing.h

drawAtPoint:forWidth:withFont:lineBreakMode:

Draws the string in a single line at the specified point in the current graphics context using the specified font and attributes.

- (CGSize)drawAtPoint:(CGPoint)point forWidth:(CGFloat)width withFont:(UIFont *)font lineBreakMode:(UILineBreakMode)lineBreakMode
Parameters
point

The location (in the coordinate system of the current graphics context) at which to draw the string. This point represents the top-left corner of the string’s bounding box.

width

The maximum width of the string.

font

The font to use for rendering.

lineBreakMode

The line break options for computing the size of the string. For a list of possible values, see NSLineBreakMode.

Return Value

The size of the rendered string. The returned values may be rounded up to the nearest whole number.

Discussion

This method draws only a single line of text, drawing as much of the string as possible using the given font and constraints. This method does not perform any line wrapping during drawing.

If the value in the width parameter is smaller than actual width of the string, truncation may occur. In that situation, the options in the lineBreakMode parameter determine where to end the text.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIStringDrawing.h

drawAtPoint:forWidth:withFont:minFontSize:actualFontSize:lineBreakMode:baselineAdjustment:

Draws the string in a single line with the specified font and attributes, adjusting the font attributes as needed to render as much of the text as possible.

- (CGSize)drawAtPoint:(CGPoint)point forWidth:(CGFloat)width withFont:(UIFont *)font minFontSize:(CGFloat)minFontSize actualFontSize:(CGFloat *)actualFontSize lineBreakMode:(UILineBreakMode)lineBreakMode baselineAdjustment:(UIBaselineAdjustment)baselineAdjustment
Parameters
point

The location (in the coordinate system of the current graphics context) at which to draw the string. This point represents the top-left corner of the string’s bounding box.

width

The maximum width of the string.

font

The font to use for rendering.

minFontSize

The minimum size to which the font may be reduced before resorting to truncation of the text.

actualFontSize

On input, a pointer to a floating-point value. On return, this value contains the actual font size that was used to render the string.

lineBreakMode

The line break options for computing the size of the string. For a list of possible values, see NSLineBreakMode.

baselineAdjustment

Specifies the vertical text-adjustment rule to use. This rule is used to determine the position of the text in cases where the text must be drawn at a smaller size.

Return Value

The size of the rendered string. The returned values may be rounded up to the nearest whole number.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIStringDrawing.h

drawAtPoint:withFont:

Draws the string in a single line at the specified point in the current graphics context using the specified font.

- (CGSize)drawAtPoint:(CGPoint)point withFont:(UIFont *)font
Parameters
point

The location (in the coordinate system of the current graphics context) at which to draw the string. This point represents the top-left corner of the string’s bounding box.

font

The font to use for rendering.

Return Value

The size of the rendered string. The returned values may be rounded up to the nearest whole number.

Discussion

This method draws only a single line of text, drawing as much of the string as possible using the given font. This method does not perform any line wrapping during drawing.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIStringDrawing.h

drawInRect:withFont:

Draws the string in the current graphics context using the specified bounding rectangle and font.

- (CGSize)drawInRect:(CGRect)rect withFont:(UIFont *)font
Parameters
rect

The bounding rectangle (in the current graphics context) in which to draw the string.

font

The font to use for rendering.

Return Value

The size of the rendered string. The returned values may be rounded up to the nearest whole number.

Discussion

This method draws as much of the string as possible using the given font and constraints. This method uses the UILineBreakModeWordWrap line break mode and the UITextAlignmentLeft alignment.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIStringDrawing.h

drawInRect:withFont:lineBreakMode:

Draws the string in the current graphics context using the specified bounding rectangle, font, and attributes.

- (CGSize)drawInRect:(CGRect)rect withFont:(UIFont *)font lineBreakMode:(UILineBreakMode)lineBreakMode
Parameters
rect

The bounding rectangle (in the current graphics context) in which to draw the string.

font

The font to use for rendering.

lineBreakMode

The line break options for computing the size of the string. For a list of possible values, see NSLineBreakMode.

Return Value

The size of the rendered string. The returned values may be rounded up to the nearest whole number.

Discussion

This method draws as much of the string as possible using the given font, line break mode, and size constraints. The text is drawn using the UITextAlignmentLeft alignment.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIStringDrawing.h

drawInRect:withFont:lineBreakMode:alignment:

Draws the string in the current graphics context using the specified bounding rectangle, font and attributes.

- (CGSize)drawInRect:(CGRect)rect withFont:(UIFont *)font lineBreakMode:(UILineBreakMode)lineBreakMode alignment:(UITextAlignment)alignment
Parameters
rect

The bounding rectangle (in the current graphics context) in which to draw the string.

font

The font to use for rendering.

lineBreakMode

The line break options for computing the size of the string. For a list of possible values, see NSLineBreakMode.

alignment

The alignment of the text inside the bounding rectangle. For a list of possible values, see “UITextAlignment.”

Return Value

The size of the rendered string. The returned values may be rounded up to the nearest whole number.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIStringDrawing.h

sizeWithFont:

Returns the size of the string if it were to be rendered with the specified font on a single line.

- (CGSize)sizeWithFont:(UIFont *)font
Parameters
font

The font to use for computing the string size.

Return Value

The width and height of the resulting string’s bounding box. These values may be rounded up to the nearest whole number.

Discussion

You can use this method to obtain the layout metrics you need to draw a string in your user interface. This method does not actually draw the string or alter the receiver’s text in any way.

In iOS 6 and later, this method wraps text using the NSLineBreakByWordWrapping option by default. In earlier versions of iOS, this method does not perform any line wrapping and returns the absolute width and height of the string using the specified font.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIStringDrawing.h

sizeWithFont:constrainedToSize:

Returns the size of the string if it were rendered and constrained to the specified size.

- (CGSize)sizeWithFont:(UIFont *)font constrainedToSize:(CGSize)size
Parameters
font

The font to use for computing the string size.

size

The maximum acceptable size for the string. This value is used to calculate where line breaks and wrapping would occur.

Return Value

The width and height of the resulting string’s bounding box. These values may be rounded up to the nearest whole number.

Discussion

You can use this method to obtain the layout metrics you need to draw a string in your user interface. This method does not actually draw the string or alter the receiver’s text in any way.

This method computes the metrics needed to draw the specified string. This method lays out the receiver’s text and attempts to make it fit the specified size using the specified font and the NSLineBreakByWordWrapping line break option. During layout, the method may break the text onto multiple lines to make it fit better. If the receiver’s text does not completely fit in the specified size, it lays out as much of the text as possible and truncates it (for layout purposes only) according to the specified line break mode. It then returns the size of the resulting truncated string. If the height specified in the size parameter is less than a single line of text, this method may return a height value that is bigger than the one specified.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIStringDrawing.h

sizeWithFont:constrainedToSize:lineBreakMode:

Returns the size of the string if it were rendered with the specified constraints.

- (CGSize)sizeWithFont:(UIFont *)font constrainedToSize:(CGSize)size lineBreakMode:(UILineBreakMode)lineBreakMode
Parameters
font

The font to use for computing the string size.

size

The maximum acceptable size for the string. This value is used to calculate where line breaks and wrapping would occur.

lineBreakMode

The line break options for computing the size of the string. For a list of possible values, see NSLineBreakMode.

Return Value

The width and height of the resulting string’s bounding box. These values may be rounded up to the nearest whole number.

Discussion

You can use this method to obtain the layout metrics you need to draw a string in your user interface. This method does not actually draw the string or alter the receiver’s text in any way.

This method computes the metrics needed to draw the specified string. This method lays out the receiver’s text and attempts to make it fit the specified size using the specified font and line break options. During layout, the method may break the text onto multiple lines to make it fit better. If the receiver’s text does not completely fit in the specified size, it lays out as much of the text as possible and truncates it (for layout purposes only) according to the specified line break mode. It then returns the size of the resulting truncated string. If the height specified in the size parameter is less than a single line of text, this method may return a height value that is bigger than the one specified.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIStringDrawing.h

sizeWithFont:forWidth:lineBreakMode:

Returns the size of the string if it were to be rendered with the specified font and line attributes on a single line.

- (CGSize)sizeWithFont:(UIFont *)font forWidth:(CGFloat)width lineBreakMode:(NSLineBreakMode)lineBreakMode
Parameters
font

The font to use for computing the string size.

width

The maximum acceptable width for the string. This value is used to calculate where line breaks would be placed.

lineBreakMode

The line break options for computing the size of the string. For a list of possible values, see NSLineBreakMode.

Return Value

The width and height of the resulting string’s bounding box. These values may be rounded up to the nearest whole number.

Discussion

You can use this method to obtain the layout metrics you need to draw a string in your user interface. This method does not actually draw the string or alter the receiver’s text in any way.

This method returns the width and height of the string constrained to the specified width. Although it computes where line breaks would occur, this method does not actually wrap the text to additional lines. If the size of the string exceeds the given width, this method truncates the text (for layout purposes only) using the specified line break mode until it does conform to the maximum width; it then returns the size of the resulting truncated string.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIStringDrawing.h

sizeWithFont:minFontSize:actualFontSize:forWidth:lineBreakMode:

Returns the size of the string if it were rendered with the specified constraints, including a variable font size, on a single line.

- (CGSize)sizeWithFont:(UIFont *)font minFontSize:(CGFloat)minFontSize actualFontSize:(CGFloat *)actualFontSize forWidth:(CGFloat)width lineBreakMode:(UILineBreakMode)lineBreakMode
Parameters
font

The font to use for computing the string size.

minFontSize

The minimum size to which the font may be reduced before resorting to truncation of the text.

actualFontSize

On input, a pointer to a floating-point value. On return, this value contains the actual font size that was used to compute the size of the string.

width

The maximum acceptable width for the string. This value is used to calculate where line breaks would be placed.

lineBreakMode

The line break options for computing the size of the string. For a list of possible values, see NSLineBreakMode.

Return Value

The width and height of the resulting string’s bounding box. These values may be rounded up to the nearest whole number.

Discussion

You can use this method to obtain the layout metrics you need to draw a string in your user interface. This method does not actually draw the string or alter the receiver’s text in any way.

Although it computes where line breaks would occur, this method does not actually wrap the text to additional lines. If the entire string does not fit within the given width using the initial font size, this method reduces the font size until the string does fit or until it reaches the specified minimum font size. If it reaches the minimum font size, the method begins truncating the text (for layout purposes only) until the resulting truncated string does fit the width; it then then returns the size of that truncated string.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIStringDrawing.h

Constants

UILineBreakMode

Options for wrapping and truncating text. (Deprecated. Use NSLineBreakMode instead.)

typedef enum {
   UILineBreakModeWordWrap = 0,
   UILineBreakModeCharacterWrap,
   UILineBreakModeClip,
   UILineBreakModeHeadTruncation,
   UILineBreakModeTailTruncation,
   UILineBreakModeMiddleTruncation,
} UILineBreakMode;
Constants
UILineBreakModeWordWrap

Wrap or clip the string only at word boundaries. This is the default wrapping option. (Deprecated. Use NSLineBreakByWordWrapping instead.)

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

UILineBreakModeCharacterWrap

Wrap or clip the string at the closest character boundary. (Deprecated. Use NSLineBreakByCharWrapping instead.)

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

UILineBreakModeClip

Clip the text when the end of the drawing rectangle is reached. This option could result in a partially rendered character at the end of a string. (Deprecated. Use NSLineBreakByClipping instead.)

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

UILineBreakModeHeadTruncation

Truncate text (as needed) from the beginning of the line. For multiple lines of text, only text on the first line is truncated. (Deprecated. Use NSLineBreakByTruncatingHead instead.)

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

UILineBreakModeTailTruncation

Truncate text (as needed) from the end of the line. For multiple lines of text, only text on the last line is truncated. (Deprecated. Use NSLineBreakByTruncatingTail instead.)

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

UILineBreakModeMiddleTruncation

Truncate text (as needed) from the middle of the line. For multiple lines of text, text is truncated only at the midpoint of the line. (Deprecated. Use NSLineBreakByTruncatingMiddle instead.)

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

Discussion

For methods that draw at a specified point (as opposed to those that draw in a rectangular region), these options specify the clipping behavior that is applied to the string.

NSTextAlignment

Options for aligning text horizontally.

enum {
   NSTextAlignmentLeft      = 0,
   NSTextAlignmentCenter    = 1,
   NSTextAlignmentRight     = 2,
   NSTextAlignmentJustified = 3,
   NSTextAlignmentNatural   = 4,
};
typedef NSInteger NSTextAlignment;
Constants
NSTextAlignmentLeft

Align text along the left edge.

Available in iOS 6.0 and later.

Declared in NSText.h.

NSTextAlignmentCenter

Align text equally along both sides of the center line.

Available in iOS 6.0 and later.

Declared in NSText.h.

NSTextAlignmentRight

Align text along the right edge.

Available in iOS 6.0 and later.

Declared in NSText.h.

NSTextAlignmentJustified

Fully justify the text so that the last line in a paragraph is natural aligned.

Available in iOS 6.0 and later.

Declared in NSText.h.

NSTextAlignmentNatural

Use the default alignment associated with the current script.

Available in iOS 6.0 and later.

Declared in NSText.h.

UITextAlignment

Options for aligning text horizontally. (Deprecated. Use “NSTextAlignment” instead.)

typedef enum {
   UITextAlignmentLeft,
   UITextAlignmentCenter,
   UITextAlignmentRight,
} UITextAlignment;
Constants
UITextAlignmentLeft

Align text along the left edge. (Deprecated. Use NSTextAlignmentLeft instead.)

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

UITextAlignmentCenter

Align text equally along both sides of the center line. (Deprecated. Use NSTextAlignmentCenter instead.)

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

UITextAlignmentRight

Align text along the right edge. (Deprecated. Use NSTextAlignmentRight instead.)

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

UIBaselineAdjustment

Vertical adjustment options. 

typedef enum {
   UIBaselineAdjustmentAlignBaselines,
   UIBaselineAdjustmentAlignCenters,
   UIBaselineAdjustmentNone,
} UIBaselineAdjustment;
Constants
UIBaselineAdjustmentAlignBaselines

Adjust text relative to the position of its baseline.

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

UIBaselineAdjustmentAlignCenters

Adjust text based relative to the center of its bounding box.

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

UIBaselineAdjustmentNone

Adjust text relative to the top-left corner of the bounding box. This is the default adjustment.

Available in iOS 2.0 and later.

Declared in UIStringDrawing.h.

Discussion

Baseline adjustment options determine how to adjust the position of text in cases where the text must be drawn using a different font size than the one originally specified. For example, with the UIBaselineAdjustmentAlignBaselines option, the position of the baseline remains fixed at its initial location while the text appears to move toward that baseline. Similarly, the UIBaselineAdjustmentNone option makes it appear as if the text is moving upwards towards the top-left corner of the bounding box.

NSWritingDirection

Constants for specifying the writing direction to use.

enum {
   NSWritingDirectionNatural = -1,
   NSWritingDirectionLeftToRight =  0,
   NSWritingDirectionRightToLeft =  1
};
typedef NSInteger NSWritingDirection;
Constants
NSWritingDirectionNatural

Use the Unicode Bidi algorithm rules P2 and P3 to determine which direction to use.

Available in iOS 6.0 and later.

Declared in NSText.h.

NSWritingDirectionLeftToRight

Use a left to right writing direction.

Available in iOS 6.0 and later.

Declared in NSText.h.

NSWritingDirectionRightToLeft

Use a right to left writing direction.

Available in iOS 6.0 and later.

Declared in NSText.h.

Keys for Text Attributes Dictionaries

Keys for dictionaries that contain text attributes.

NSString *const UITextAttributeFont;
NSString *const UITextAttributeTextColor;
NSString *const UITextAttributeTextShadowColor;
NSString *const UITextAttributeTextShadowOffset;
Constants
UITextAttributeFont

Key to the font in a text attributes dictionary.

The corresponding value is an instance of UIFont.

Use a font with size 0.0 to get the default font size for the current context.

Available in iOS 5.0 and later.

Declared in UIStringDrawing.h.

UITextAttributeTextColor

Key to the text color in a text attributes dictionary.

The corresponding value is an instance of UIColor.

Available in iOS 5.0 and later.

Declared in UIStringDrawing.h.

UITextAttributeTextShadowColor

Key to the text shadow color in a text attributes dictionary.

The corresponding value is an instance of UIColor.

Available in iOS 5.0 and later.

Declared in UIStringDrawing.h.

UITextAttributeTextShadowOffset

Key to the offset used for the text shadow in a text attributes dictionary.

The corresponding value is an instance of NSValue wrapping a UIOffset struct.

Available in iOS 5.0 and later.

Declared in UIStringDrawing.h.



© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-12-13)

Did this document help you? Yes It's good, but... Not helpful...