NSString UIKit Additions Reference

Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
NSStringDrawing.h
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

boundingRectWithSize:options:attributes:context:

Calculates and returns the bounding rect for the receiver drawn using the given options and display characteristics, within the specified rectangle in the current graphics context.

- (CGRect)boundingRectWithSize:(CGSize)size options:(NSStringDrawingOptions)options attributes:(NSDictionary *)attributes context:(NSStringDrawingContext *)context
Parameters
size

The size of the rectangle to draw in.

options

String drawing options.

attributes

A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

context

The string drawing context to use for the receiver, specifying minimum scale factor and tracking adjustments.

Return Value

The bounding rect for the receiver drawn using the given options and display characteristics. The rect origin returned from this method is the first glyph origin.

Discussion

To correctly draw and size multi-line text, pass NSStringDrawingUsesLineFragmentOrigin in the options parameter.

This method returns fractional sizes (in the size component of the returned CGRect); to use a returned size to size views, you must raise its value to the nearest higher integer using the ceil function.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSStringDrawing.h

drawAtPoint:withAttributes:

Draws the receiver with the font and other display characteristics of the given attributes, at the specified point in the current graphics context.

- (void)drawAtPoint:(CGPoint)point withAttributes:(NSDictionary *)attrs
Parameters
point

The point in the current graphics context where you want to start drawing the string. The coordinate system of the graphics context is usually defined by the view in which you are drawing.

attrs

A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

Discussion

The width (height for vertical layout) of the rendering area is unlimited, unlike drawInRect:withAttributes:, which uses a bounding rectangle. As a result, this method renders the text in a single line. However, if newline characters are present in the string, those characters are honored and cause subsequent text to be placed on the next line underneath the starting point.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSStringDrawing.h

drawInRect:withAttributes:

Draws the attributed string inside the specified bounding rectangle in the current graphics context.

- (void)drawInRect:(CGRect)rect withAttributes:(NSDictionary *)attrs
Parameters
rect

The bounding rectangle in which to draw the string.

attrs

The text attributes with which to draw the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

Discussion

This method draws as much of the string as it can inside the specified rectangle, wrapping the string text as needed to make it fit. If the string is too long to fit inside the rectangle, the method renders as much as possible and clips the rest.

If newline characters are present in the string, those characters are honored and cause subsequent text to be placed on the next line underneath the starting point.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSStringDrawing.h

drawWithRect:options:attributes:context:

Draws the attributed string in the specified bounding rectangle using the provided options.

- (void)drawWithRect:(CGRect)rect options:(NSStringDrawingOptions)options attributes:(NSDictionary *)attributes context:(NSStringDrawingContext *)context
Parameters
rect

The bounding rectangle in which to draw the string.

options

Additional drawing options to apply to the string during rendering. For a list of possible values, see NSStringDrawingOptions.

attributes

The text attributes with which to draw the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

context

A context object with information about how to adjust the font tracking and scaling information. On return, the specified object contains information about the actual values used to render the string. This parameter may be nil.

Discussion

This method draws as much of the string as it can inside the specified rectangle, wrapping the string text as needed to make it fit. If the string is too big to fit completely inside the rectangle, the method scales the font or adjusts the letter spacing to make the string fit within the given bounds.

If newline characters are present in the string, those characters are honored and cause subsequent text to be placed on the next line underneath the starting point. To correctly draw and size multi-line text, pass NSStringDrawingUsesLineFragmentOrigin in the options parameter.

Special Considerations

This method uses the baseline origin by default.

If NSStringDrawingUsesLineFragmentOrigin is not specified, the rectangle’s height will be ignored and the operation considered to be single-line rendering.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSStringDrawing.h

sizeWithAttributes:

Returns the bounding box size the receiver occupies when drawn with the given attributes.

- (CGSize)sizeWithAttributes:(NSDictionary *)attrs
Parameters
attrs

A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

Return Value

The bounding box size the receiver occupies when drawn with the specified attributes.

Discussion

This method returns fractional sizes; to use a returned size to size views, you must raise its value to the nearest higher integer using the ceil function.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSStringDrawing.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.

Deprecated in iOS 7.0.

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.

Deprecated in iOS 7.0.

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.

Deprecated in iOS 7.0.

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.

Deprecated in iOS 7.0.

Declared in UIStringDrawing.h.