NSAttributedString UIKit Additions Reference

Framework	/System/Library/Frameworks/UIKit.framework
Availability	Available in iOS 6.0 and later.
Declared in	NSAttributedString.h NSStringDrawing.h

Overview

The UIKit framework adds methods to NSAttributedString to support the drawing of styled strings and to compute the size and metrics of a string prior to drawing. None of these methods affects the contents of the 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.

You may use the methods described in this class extension from secondary threads in your app and not just from the main thread. However, if you use any of the methods that support an NSStringDrawingContext object, you must not share contexts across threads or dispatch queues.

Tasks

Drawing the String

Getting Metrics for the String

Instance Methods

boundingRectWithSize:options:context:

Returns the bounding rectangle required to draw the string.

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

Parameters

size: The width and height constraints to apply when computing the string’s bounding rectangle.
options: Additional drawing options to apply to the string during rendering. For a list of possible values, see “NSStringDrawingOptions”.
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.

Return Value

A rectangle whose size component indicates the width and height required to draw the entire contents of the string.

Discussion

You can use this method to compute the space required to draw the string. The constraints you specify in the size parameter are a guide for the renderer for how to size the string. However, the actual bounding rectangle returned by this method can be larger than the constraints if additional space is needed to render the entire string. Typically, the renderer preserves the width constraint and adjusts the height constraint as needed.

Special Considerations

To calculate the bounding rectangle, 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. (Due to a bug, the width is also ignored on iOS 6.)

Availability

Available in iOS 6.0 and later.

Declared In

NSStringDrawing.h

drawAtPoint:

Draws the attributed string starting at the specified point in the current graphics context.

- (void)drawAtPoint:(CGPoint)point

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.

Discussion

This method draws the entire string starting at the specified point. This method draws the line using the attributes specified in the attributed string itself. 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 6.0 and later.

Declared In

NSStringDrawing.h

drawInRect:

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

- (void)drawInRect:(CGRect)rect

Parameters

rect: The bounding rectangle in which to draw 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.

This method draws the line using the attributes specified in the attributed string itself. 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 6.0 and later.

Declared In

NSStringDrawing.h

drawWithRect:options:context:

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

- (void)drawWithRect:(CGRect)rect options:(NSStringDrawingOptions)options 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”.
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.

Special Considerations

This method uses the baseline origin by default.

Availability

Available in iOS 6.0 and later.

Declared In

NSStringDrawing.h

size

Returns the size required to draw the string.

- (CGSize)size

Return Value

The minimum size required to draw the entire contents of the string.

Discussion

You can use this method prior to drawing to compute how much space is required to draw the string.

Availability

Available in iOS 6.0 and later.

Declared In

NSStringDrawing.h

Constants

NSStringDrawingOptions

Options for customizing the way strings are drawn.

enum {
   NSStringDrawingTruncatesLastVisibleLine = 1 << 5,
   NSStringDrawingUsesLineFragmentOrigin = 1 << 0,
   NSStringDrawingUsesFontLeading = 1 << 1,
   NSStringDrawingUsesDeviceMetrics = 1 << 3,
};
typedef NSInteger NSStringDrawingOptions;

Constants

NSStringDrawingTruncatesLastVisibleLine

Truncate and add an ellipsis character to the last visible line if the text does not fit into the specified bounds. This option is ignored if the NSStringDrawingUsesLineFragmentOrigin option is not also specified.

Available in iOS 6.0 and later.

Declared in NSStringDrawing.h.

NSStringDrawingUsesLineFragmentOrigin

The origin specified when drawing the string is the line fragment origin and not the baseline origin.

Available in iOS 6.0 and later.

Declared in NSStringDrawing.h.

NSStringDrawingUsesFontLeading

Use the font leading information to calculate line heights.

Available in iOS 6.0 and later.

Declared in NSStringDrawing.h.

NSStringDrawingUsesDeviceMetrics

Use the image glyph bounds (instead of the typographic bounds) when computing layout.

Available in iOS 6.0 and later.

Declared in NSStringDrawing.h.

Underline Style Attributes

Constants for specifying the underline or strikethrough line style.

enum {
   NSUnderlineStyleNone = 0x00,
   NSUnderlineStyleSingle = 0x01,
};

Constants

NSUnderlineStyleNone

Do not draw a line.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSUnderlineStyleSingle

Draw a single line.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

Discussion

You can use these constants for both the NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName attributes of an attributed string.

Character Attributes

Attributes that you can apply to text in an attributed string.

NSString *const NSFontAttributeName;
NSString *const NSParagraphStyleAttributeName;
NSString *const NSForegroundColorAttributeName;
NSString *const NSBackgroundColorAttributeName;
NSString *const NSLigatureAttributeName;
NSString *const NSKernAttributeName;
NSString *const NSStrikethroughStyleAttributeName;
NSString *const NSUnderlineStyleAttributeName;
NSString *const NSStrokeColorAttributeName;
NSString *const NSStrokeWidthAttributeName;
NSString *const NSShadowAttributeName;
NSString *const NSVerticalGlyphFormAttributeName;

Constants

NSFontAttributeName

The value of this attribute is a UIFont object. Use this attribute to change the font for a range of text. If you do not specify this attribute, the string uses a 12-point Helvetica(Neue) font by default.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSParagraphStyleAttributeName

The value of this attribute is an NSParagraphStyle object. Use this attribute to apply multiple attributes to a range of text. If you do not specify this attribute, the string uses the default paragraph attributes, as returned by the defaultParagraphStyle method of NSParagraphStyle.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSForegroundColorAttributeName

The value of this attribute is a UIColor object. Use this attribute to specify the color of the text during rendering. If you do not specify this attribute, the text is rendered in black.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSBackgroundColorAttributeName

The value of this attribute is a UIColor object. Use this attribute to specify the color of the background area behind the text. If you do not specify this attribute, no background color is drawn.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSLigatureAttributeName

The value of this attribute is an NSNumber object containing an integer. Ligatures cause specific character combinations to be rendered using a single custom glyph that corresponds to those characters. The value 0 indicates no ligatures. The value 1 indicates the use of the default ligatures. The value 2 indicates the use of all ligatures. The default value for this attribute is 1. (Note that value 2 is unsupported on iOS.)

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSKernAttributeName

The value of this attribute is an NSNumber object containing a floating-point value. This value specifies the number of points by which to adjust kern-pair characters. Kerning prevents unwanted space from occurring between specific characters and depends on the font. The value 0 means kerning is disabled. The default value for this attribute is 0.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSStrikethroughStyleAttributeName

The value of this attribute is an NSNumber object containing an integer. This value indicates whether the text has a line through it and corresponds to one of the constants described in “Underline Style Attributes”. The default value for this attribute is NSUnderlineStyleNone.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSUnderlineStyleAttributeName

The value of this attribute is an NSNumber object containing an integer. This value indicates whether the text is underlined and corresponds to one of the constants described in “Underline Style Attributes”. The default value for this attribute is NSUnderlineStyleNone.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSStrokeColorAttributeName

The value of this parameter is a UIColor object. If it is not defined (which is the case by default), it is assumed to be the same as the value of NSForegroundColorAttributeName; otherwise, it describes the outline color. For more details, see Drawing attributed strings that are both filled and stroked.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSStrokeWidthAttributeName

The value of this attribute is an NSNumber object containing a floating-point value. This value represents the amount to change the stroke width and is specified as a percentage of the font point size. Specify 0 (the default) for no additional changes. Specify positive values to change the stroke width alone. Specify negative values to stroke and fill the text. For example, a typical value for outlined text would be 3.0.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSShadowAttributeName

The value of this attribute is an NSShadow object. The default value of this property is nil.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

NSVerticalGlyphFormAttributeName

The value of this attribute is an NSNumber object containing an integer. The value 0 indicates horizontal text. The value 1 indicates vertical text. In iOS, horizontal text is always used and specifying a different value is undefined.

Available in iOS 6.0 and later.

Declared in NSAttributedString.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.