Class

NSAttributedString

A string that has associated attributes (such as visual style, hyperlinks, or accessibility data) for portions of its text.

Declaration

@interface NSAttributedString : NSObject

Overview

An NSAttributedString object manages character strings and associated sets of attributes (for example, font and kerning) that apply to individual characters or ranges of characters in the string. An association of characters and their attributes is called an attributed string. The cluster’s two public classes, NSAttributedString and NSMutableAttributedString, declare the programmatic interface for read-only attributed strings and modifiable attributed strings, respectively.

An attributed string identifies attributes by name, using an NSDictionary object to store a value under the given name. You can assign any attribute name/value pair you wish to a range of characters—it is up to your application to interpret custom attributes (see Attributed String Programming Guide). If you are using attributed strings with the Core Text framework, you can also use the attribute keys defined by that framework.

You use attributed strings with any APIs that accept them, such as Core Text. The AppKit and UIKit frameworks also provide a subclass of NSMutableAttributedString, called NSTextStorage, to provide the storage for the extended text-handling system. In iOS 6 and later you can use attributed strings to display formatted text in text views, text fields, and some other controls. Both AppKit and UIKit also define extensions to the basic attributed string interface that allows you to draw their contents in the current graphic context.

The default font for NSAttributedString objects is Helvetica 12-point, which may differ from the default system font for the platform. Thus, you might want to create new strings with non-default attributes suitable for your application. You can also use the NSParagraphStyle class and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString classes.

Be aware that comparisons of NSAttributedString objects using the isEqual: method look for exact equality. The comparison includes both a character-by-character string equality check and an equality check of all attributes. Such a comparison is not likely to yield a match if the string has many attributes, such as attachments, lists, and tables, for example.

The NSAttributedString class is “toll-free bridged” with its Core Foundation counterpart, CFAttributedStringRef. See Toll-Free Bridging for more information.

Topics

Creating an NSAttributedString Object

- initWithString:

Returns an NSAttributedString object initialized with the characters of a given string and no attribute information.

- initWithString:attributes:

Returns an NSAttributedString object initialized with a given string and attributes.

- initWithAttributedString:

Returns an NSAttributedString object initialized with the characters and attributes of another given attributed string.

- initWithData:options:documentAttributes:error:

Initializes and returns a new attributed string object from the data contained in the given data object.

- initWithDocFormat:documentAttributes:

Initializes and returns a new NSAttributedString object from Microsoft Word format data contained in the given NSData object.

- initWithHTML:documentAttributes:

Initializes and returns a new NSAttributedString object from HTML contained in the given data object.

- initWithHTML:baseURL:documentAttributes:

Initializes and returns a new NSAttributedString object from the HTML contained in the given object and base URL.

- initWithHTML:options:documentAttributes:

Initializes and returns a new attributed string object from HTML contained in the given data object.

- initWithRTF:documentAttributes:

Initializes a new attributed string object by decoding the stream of RTF commands and data contained in the given data object.

- initWithRTFD:documentAttributes:

Initializes a new attributed string object by decoding the stream of RTFD commands and data contained in the given data object.

- initWithRTFDFileWrapper:documentAttributes:

Initializes a new attributed string object from the specified file wrapper containing an RTFD document.

- initWithURL:options:documentAttributes:error:

Initializes a new NSAttributedString object from the contents of the given URL.

+ attributedStringWithAttachment:

Creates an attributed string with an attachment.

Retrieving Character Information

string

The character contents of the receiver as an NSString object.

length

The length of the receiver’s string object.

Retrieving Attribute Information

- attributesAtIndex:effectiveRange:

Returns the attributes for the character at a given index.

- attributesAtIndex:longestEffectiveRange:inRange:

Returns the attributes for the character at a given index, and by reference the range over which the attributes apply.

- attribute:atIndex:effectiveRange:

Returns the value for an attribute with a given name of the character at a given index, and by reference the range over which the attribute applies.

- attribute:atIndex:longestEffectiveRange:inRange:

Returns the value for the attribute with a given name of the character at a given index, and by reference the range over which the attribute applies.

Comparing Attributed Strings

- isEqualToAttributedString:

Returns a Boolean value that indicates whether the receiver is equal to another given attributed string.

Extracting a Substring

- attributedSubstringFromRange:

Returns an NSAttributedString object consisting of the characters and attributes within a given range in the receiver.

Enumerating over Attributes in a String

- enumerateAttribute:inRange:options:usingBlock:

Executes the specified block for each range of a particular attribute in the attributed string.

- enumerateAttributesInRange:options:usingBlock:

Executes the specified block for each range of attributes in the attributed string.

Retrieving Font Attribute Information

- fontAttributesInRange:

Returns the font attributes in effect for the character at the given location.

- rulerAttributesInRange:

Returns the ruler (paragraph) attributes in effect for the characters within the given range.

Calculating Linguistic Units

- doubleClickAtIndex:

Returns the range of characters that form a word (or other linguistic unit) surrounding the given index, taking language characteristics into account.

- lineBreakBeforeIndex:withinRange:

Returns the appropriate line break when the character at the index won’t fit on the same line as the character at the beginning of the range.

- lineBreakByHyphenatingBeforeIndex:withinRange:

Returns the index of the closest character before the given index, and within the given range, that can be placed on a new line by hyphenating.

- nextWordFromIndex:forward:

Returns the index of the first character of the word after or before the given index.

Calculating Ranges

- itemNumberInTextList:atIndex:

Returns the index of the item at the given location within the list.

- rangeOfTextBlock:atIndex:

Returns the range of the individual text block that contains the given location.

- rangeOfTextList:atIndex:

Returns the range of the given text list that contains the given location.

- rangeOfTextTable:atIndex:

Returns the range of the given text table that contains the given location

Generating Data

- dataFromRange:documentAttributes:error:

Returns an data object that contains a text stream corresponding to the characters and attributes within the given range.

- fileWrapperFromRange:documentAttributes:error:

Returns an NSFileWrapper object that contains a text stream corresponding to the characters and attributes within the given range.

- docFormatFromRange:documentAttributes:

Returns a data object that contains a Microsoft Word–format stream corresponding to the characters and attributes within the specified range.

- RTFFromRange:documentAttributes:

Returns an NSData object that contains an RTF stream corresponding to the characters and attributes within the given range, omitting all attachment attributes.

- RTFDFromRange:documentAttributes:

Returns a data object that contains an RTFD stream corresponding to the characters and attributes within the range.

- RTFDFileWrapperFromRange:documentAttributes:

Returns an NSFileWrapper object that contains an RTFD document corresponding to the characters and attributes within the given range.

Drawing the String

- drawAtPoint:

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

- drawInRect:

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

- drawWithRect:options:context:

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

Getting Metrics for the String

- size

Returns the size required to draw the string.

- boundingRectWithSize:options:context:

Returns the bounding rectangle required to draw the string.

- containsAttachmentsInRange:

Returns a Boolean value that indicates if the attributed string contains a property configured in the specified range.

Testing String Data Sources

textTypes

Returns an array of UTI strings identifying the file types supported by the receiver, either directly or through a user-installed filter service.

textUnfilteredTypes

Returns an array of UTI strings identifying the file types supported directly by the receiver.

Constants

NSAttributedStringKey

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

NSAttributedStringDocumentAttributeKey

Attributes that apply to a document.

NSAttributedStringDocumentType

Constants that can be returned for the document type in the document attributes dictionary.

NSSpellingState

Values for the NSSpellingStateAttributeName attribute key.

NSUnderlineStrikethroughMask

These constants define the underline mask.

NSWritingDirectionFormatType

Options for specifying writing direction used with NSWritingDirectionAttributeName.

NSTextWritingDirection

Options for specifying text writing direction used with NSWritingDirectionAttributeName.

Deprecated
NSUnderlineStyle

Constants for specifying both the NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName attributes of an attributed string.

Attributes for Generating HTML

These document-wide attributes provide control over the form of generated HTML—you use them only for writing HTML

Deprecated Methods

+ textFileTypes

Returns an array of strings representing those file types that can be loaded as text.

Deprecated
+ textUnfilteredFileTypes

Returns an array of strings representing those file types that can be loaded as a text.

Deprecated
+ textPasteboardTypes

Returns an array of pasteboard types that can be loaded as text.

Deprecated
+ textUnfilteredPasteboardTypes

Returns an array of pasteboard types that can be loaded as text.

Deprecated
- initWithPath:documentAttributes:

Initializes a new attribute string object from RTF or RTFD data contained in the file at the given path.

Deprecated
- initWithURL:documentAttributes:

Initializes a new attributed string object from the data at the given URL.

Deprecated
- initWithFileURL:options:documentAttributes:error:

Initializes a new attributed string object from the data at the given URL.

Deprecated
containsAttachments

Returns whether the attribute string contains any attachment attributes.

Deprecated
- URLAtIndex:effectiveRange:

Returns a URL, either from a link attribute or from text at the given location that appears to be a URL string, for use in automatic link detection.

Deprecated
- drawWithRect:options:

Draws the receiver with the specified options, within the given rectangle in the current graphics context.

Deprecated
- boundingRectWithSize:options:

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

Deprecated

Relationships

Inherits From

See Also

Strings with Metadata

NSMutableAttributedString

A mutable string object that also contains attributes (such as visual style, hyperlinks, or accessibility data) associated with various portions of its text content.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software