---

NSAttributedString

Overview

NSAttributedString objects manage 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 classes NSAttributedString and NSMutableAttributedString declare the programmatic interface for read-only attributed strings and modifiable attributed strings, respectively. Methods supporting the drawing of NSAttributedStrings are found in the Application Kit class NSGraphics. The Application Kit uses a subclass of NSMutableAttributedString, called NSTextStorage, to provide the storage for the Application Kit’s extended text-handling system.

The Application Kit also uses NSParagraphStyle and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString classes.

The mutable subclass of NSAttributedString is NSMutableAttributedString.

Note that the default font for NSAttributedString objects is Helvetica 12-point, which differs from the Mac OS X system font Lucida Grande, so you may wish to create the string with non-default attributes suitable for your application.

Tasks

Constructors

• NSAttributedString

Retrieving Character Information

• stringReference
• length

Retrieving Attribute Information

• attributesAtIndex
• attributeAtIndex

Comparing Attributed Strings

• isEqualToAttributedString

Extracting a Substring

• attributedSubstringWithRange

Retrieving General Information

• containsAttachments
• doubleClickAtIndex
• fontAttributesInRange
• lineBreakBeforeIndex
• lineBreakByHyphenatingBeforeIndex
• nextWordFromIndex
• rulerAttributesInRange

Generating Data

• RTFDFileWrapperFromRange
• RTFFromRange
• docFormatFromRange

Instance Methods

attributeAtIndex

Returns the value for the attribute named attributeName of the character at index, or null if there is no such attribute.

public Object attributeAtIndex(String attributeName, int index, NSMutableRange aRange)

Discussion

If the named attribute exists at index and aRange is non-null, it’s filled with a range over which the named attribute’s value applies. If the named attribute doesn’t exist at index and aRange is non-null, aRange is filled instead with the range over which the attribute doesn’t exist. This range isn’t necessarily the maximum range covered by attributeName, and its extent is implementation-dependent.

Throws an exception if index lies beyond the end of the receiver’s characters.

Returns the value for the attribute named attributeName of the character at index, or null if there is no such attribute.

public Object attributeAtIndex(String attributeName, int index, NSMutableRange aRange, NSRange rangeLimit)

Discussion

If the named attribute exists at index and aRange is non-null, it’s filled with the full range over which the value of the named attribute is the same as that at index, clipped to rangeLimit. If the named attribute doesn’t exist at index and aRange is non-null, aRange is filled instead with the full range over which the attribute doesn’t exist, clipped to rangeLimit.

Throws an exception if index or any part of rangeLimit lies beyond the end of the receiver’s characters.

See Also

• attributesAtIndex

attributedSubstringWithRange

Returns an NSAttributedString object consisting of the characters and attributes within aRange in the receiver.

public NSAttributedString attributedSubstringWithRange(NSRange aRange)

Discussion

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters. This method treats the length of the string as a valid range value that returns an empty string.

attributesAtIndex

Returns the attributes for the character at index.

public NSDictionary attributesAtIndex(int index, NSMutableRange aRange)

Discussion

If aRange is non-null it’s filled with the range over which the attributes and values are the same as those at index. This range isn’t necessarily the maximum range covered, and its extent is implementation-dependent.

Throws an exception if index lies beyond the end of the receiver’s characters.

Returns the attributes for the character at index.

public NSDictionary attributesAtIndex(int index, NSMutableRange aRange, NSRange rangeLimit)

Discussion

If aRange is non-null, it’s filled with the maximum range over which the attributes and values are the same as those at index, clipped to rangeLimit.

Throws an exception if index or any part of rangeLimit lies beyond the end of the receiver’s characters.

See Also

• attributeAtIndex

containsAttachments

Returns true if the receiver contains any attachment attributes, false otherwise.

public boolean containsAttachments()

Discussion

This method checks only for attachment attributes, not for NSAttachmentCharacter.

docFormatFromRange

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

public NSData docFormatFromRange(NSRange range, NSDictionary dict)

Discussion

The range is passed in the range parameter. Also writes the document-level attributes in dict, as explained in “Constants.” If there are no document-level attributes, dict can be null. Throws an NSRangeException if any part of range lies beyond the end of the receiver’s characters.

Availability

• Available in Mac OS X v10.3 and later.

doubleClickAtIndex

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

public NSRange doubleClickAtIndex(int index)

Discussion

Throws a RangeException if index lies beyond the end of the receiver’s characters.

See Also

• nextWordFromIndex

fontAttributesInRange

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

public NSDictionary fontAttributesInRange(NSRange aRange)

Discussion

Use this method to obtain font attributes that are to be copied or pasted with “copy font” operations. Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

• rulerAttributesInRange

isEqualToAttributedString

Returns true if the receiver is equal to otherString.

public boolean isEqualToAttributedString(NSAttributedString otherString)

Discussion

Attributed strings must match in both characters and attributes to be equal.

length

Returns the length of the receiver’s string object.

public int length()

See Also

• length (NSStringReference)

lineBreakBeforeIndex

Returns the index of the closest character before index and within aRange that can be placed on a new line when laying out text.

public int lineBreakBeforeIndex(int index, NSRange aRange)

Discussion

In other words, finds the appropriate line break when the character at index won’t fit on the same line as the character at the beginning of aRange. Returns NSArray.NotFound if no line break is possible before index.Throws a RangeException if index or any part of aRange lies beyond the end of the receiver’s characters.

See Also

• lineBreakByHyphenatingBeforeIndex

lineBreakByHyphenatingBeforeIndex

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

public int lineBreakByHyphenatingBeforeIndex(int location, NSRange aRange)

Discussion

In other words, during text layout, finds the appropriate line break by hyphenation (the character index at which the hyphen glyph should be inserted) when the character at index won’t fit on the same line as the character at the beginning of aRange. Returns NSArray.NotFound if no line break by hyphenation is possible before index.Throws a RangeException if index or any part of aRange lies beyond the end of the receiver’s characters.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• lineBreakBeforeIndex

nextWordFromIndex

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

public int nextWordFromIndex(int index, boolean flag)

Discussion

If flag is true, this is the first character after index that begins a word; if flag is false, it’s the first character before index that begins a word, whether index is located within a word or not. If index lies at either end of the string and the search direction would progress past that end, it’s returned unchanged. This method is intended for moving the insertion point during editing, not for linguistic analysis or parsing of text.Throws a RangeException if index lies beyond the end of the receiver’s characters.

See Also

• lineBreakBeforeIndex

RTFDFileWrapperFromRange

Returns an object that contains an RTFD document corresponding to the characters and attributes within aRange.

public Object RTFDFileWrapperFromRange(NSRange aRange, NSDictionary docAttributes)

Discussion

The file wrapper also includes the document-level attributes in docAttributes. If there are no document-level attributes, docAttributes can be null. Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.You can save the file wrapper using NSFileWrapper’s writeToFile.

See Also

• RTFFromRange

RTFFromRange

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

public NSData RTFFromRange(NSRange aRange, NSDictionary docAttributes)

Discussion

Also writes the document-level attributes in docAttributes. If there are no document-level attributes, docAttributes can be null. Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.When writing data to the pasteboard, you can use the NSData object as the first argument to NSPasteboard’s setDataForType, with a second argument of NSPasteboard.RTFPboardType.Although this method strips attachments, it leaves the attachment characters in the text itself. NSText’s RTFFromRange, on the other hand, does strip attachment characters when extracting RTF.

See Also

• RTFDFileWrapperFromRange

rulerAttributesInRange

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

public NSDictionary rulerAttributesInRange(NSRange aRange)

Discussion

The only ruler attribute currently defined is that named by NSParagraphStyleAttributeName. Use this method to obtain attributes that are to be copied or pasted with “copy ruler” operations. Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

• fontAttributesInRange

stringReference

Returns the character contents of the receiver as an NSStringReference object.

public NSStringReference stringReference()

Discussion

This method doesn’t strip out attachment characters; use NSText’s string method to extract just the linguistically significant characters.

For performance reasons, this method returns the current backing store of the attributed string object. If you want to maintain a snapshot of this as you manipulate the returned string, you should make a copy of the appropriate substring.

This primitive method must guarantee efficient access to an attributed string’s characters; subclasses should implement it to execute in O(1) time.

Constants

NSAttributedString provides the following attribute name constants:

NSAttributedString provides the following constants to use when working with underlines:

The following constants previously used for underline style were deprecated in Mac OS X v10.3:

• NoUnderlineStyle

• SingleUnderlineStyle

• UnderlineStrikethroughMask

The constructors can return a dictionary with the following document-wide attributes:

The following values can be returned for the DocumentType key in the document attributes dictionary:

---