NSAttributedString Application Kit Additions Reference

Inherits from	NSObject
Framework	/System/Library/Frameworks/AppKit.framework
Companion guide	Attributed String Programming Guide
Declared in	NSAttributedString.h NSStringDrawing.h NSTextAttachment.h

Overview

The Application Kit extends Foundation’s NSAttributedString class by adding support for RTF, RTFD, and HTML (with or without attachments), graphics attributes (including font and ruler attributes), methods for drawing attributed strings, and methods for calculating significant linguistic units.

Tasks

Creating an NSAttributedString

Retrieving Font Attribute Information

Calculating Linguistic Units

Calculating Ranges

Generating Data

Drawing the String

Getting the Bounding Rectangle of Rendered Strings

Testing String Data Sources

Deprecated Methods

Class Methods

attributedStringWithAttachment:

Creates an attributed string with an attachment.

+ (NSAttributedString *)attributedStringWithAttachment:(NSTextAttachment *)attachment

Parameters

attachment: The attachment.

Return Value

An attributed string containing the attachment.

Availability

Available in OS X v10.0 and later.

Related Sample Code

TextEdit

Declared In

NSTextAttachment.h

textTypes

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

+ (NSArray *)textTypes

Return Value

An array of NSString objects, each of which contains a UTI identifying a supported file type.

Discussion

The returned list includes UTIs all file types supported by the receiver plus those that can be opened by the receiver after being converted by a user-installed filter service. You can use the returned UTI strings with any method that supports UTIs.

Availability

Available in OS X v10.5 and later.

Declared In

NSAttributedString.h

textUnfilteredTypes

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

+ (NSArray *)textUnfilteredTypes

Return Value

An array of NSString objects, each of which contains a UTI identifying a supported file type.

Discussion

The returned list includes UTI strings only for those file types that are supported directly by the receiver. It does not include types that are supported through user-installed filter services. You can use the returned UTI strings with any method that supports UTIs.

Availability

Available in OS X v10.5 and later.

Declared In

NSAttributedString.h

Instance Methods

boundingRectWithSize:options:

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

- (NSRect)boundingRectWithSize:(NSSize)size options:(NSStringDrawingOptions)options

Parameters

size: The size of the rectangle to draw in.
options: The string drawing options. See NSStringDrawingOptions for the possible values.

Return Value

The bounding rectangle in the current graphics context.

Discussion

The origin of the rectangle returned from this method is the first glyph origin.

Availability

Available in OS X v10.4 and later.

Declared In

NSStringDrawing.h

containsAttachments

Returns whether the attribute string contains any attachment attributes.

- (BOOL)containsAttachments

Return Value

YES if the attributed string contains any attachment attributes, otherwise NO.

Discussion

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

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

dataFromRange:documentAttributes:error:

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

- (NSData *)dataFromRange:(NSRange)range documentAttributes:(NSDictionary *)docAttributes error:(NSError **)error

Parameters

range: The range.
docAttributes: A required dictionary specifying the document attributes. The dictionary contains values from “Document Types” and must at least contain NSDocumentTypeDocumentAttribute.
error: An in-out variable containing an encountered error, if any.

Return Value

Returns the data for the attributed string, or nil if failure. When nil, error encapsulates the error information.

Discussion

Raises an NSRangeException if any part of range lies beyond the end of the receiver’s characters.

Availability

Available in OS X v10.4 and later.

Related Sample Code

TextEdit

Declared In

NSAttributedString.h

docFormatFromRange:documentAttributes:

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

- (NSData *)docFormatFromRange:(NSRange)range documentAttributes:(NSDictionary *)docAttributes

Parameters

range: The range.
docAttributes: A required dictionary specifying the document attributes. The dictionary contains values from “Document Types” and must at least contain NSDocumentTypeDocumentAttribute. If there are no document-level attributes, dict can be nil.

Return Value

Returns a data object containing the attributed string as a Microsoft Word doc file..

Discussion

Raises an NSRangeException if any part of range lies beyond the end of the receiver’s characters.

Availability

Available in OS X v10.3 and later.

Declared In

NSAttributedString.h

doubleClickAtIndex:

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

- (NSRange)doubleClickAtIndex:(NSUInteger)index

Parameters

index: The index in the attributed string.

Return Value

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

Discussion

Raises an NSRangeException if index lies beyond the end of the receiver’s characters.

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

drawAtPoint:

Draws the receiver with its font and other display attributes at the given point in the currently focused view.

- (void)drawAtPoint:(NSPoint)point

Parameters

point: The point in the current view to draw the text.

Discussion

The width (height for vertical layout) of the rendering area is unlimited, unlike drawInRect:, which uses a bounding rectangle. As a result, this method renders the text in a single line.

Don’t invoke this method when no NSView is focused.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSStringDrawing.h

drawInRect:

Draws the attributed string within the given rectangle in the currently view, clipping the text layout to this rectangle.

- (void)drawInRect:(NSRect)rect

Parameters

rect: The rectangle in which to draw.

Discussion

Text is drawn within rect according to its line sweep direction; for example, Arabic text will begin at the right edge and potentially be clipped on the left.

The rect parameter determines how many glyphs are typeset within the width of a line, but it’s possible for a portion of a glyph to appear outside the area of rect if the image bounding box of the particular glyph exceeds its typographic bounding box.

If the focus view is flipped, the text origin is set at the upper-left corner of the drawing bounding box; otherwise the origin is set at the lower-left corner. For text rendering, whether the view coordinates are flipped or not doesn't affect the flow of line layout, which goes from top to bottom. However, it affects the interpretation of the text origin. So, for example, if the rect argument is {0.0, 0.0, 100.0, 100.0}, the text origin is {0.0, 0.0} when the view coordinates are flipped and {0.0, 100.0} when not.

Don’t invoke this method when no NSView is focused.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSStringDrawing.h

drawWithRect:options:

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

- (void)drawWithRect:(NSRect)rect options:(NSStringDrawingOptions)options

Parameters

rect: The rectangle specifies the rendering origin in the current graphics context.
options: The string drawing options. See NSStringDrawingOptions for the available options..

Discussion

The rect argument's origin field specifies the rendering origin. The point is interpreted as the baseline origin by default. With NSStringDrawingUsesLineFragmentOrigin, it is interpreted as the upper left corner of the line fragment rect. The size field specifies the text container size. The width part of the size field specifies the maximum line fragment width if larger than 0.0. The height defines the maximum size that can be occupied with text if larger than 0.0 and NSStringDrawingUsesLineFragmentOrigin is specified. If NSStringDrawingUsesLineFragmentOrigin is not specified, height is ignored and considered to be single-line rendering (NSLineBreakByWordWrapping and NSLineBreakByCharWrapping are treated as NSLineBreakByClipping).

You should only invoke this method when there is a current graphics context.

Availability

Available in OS X v10.4 and later.

Declared In

NSStringDrawing.h

fileWrapperFromRange:documentAttributes:error:

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

- (NSFileWrapper *)fileWrapperFromRange:(NSRange)range documentAttributes:(NSDictionary *)docAttributes error:(NSError **)error

Parameters

range: The range.
docAttributes: A required dictionary specifying the document attributes. The dictionary contains values from “Document Types” and must at least contain NSDocumentTypeDocumentAttribute.
error: An in-out variable containing an encountered error, if any.

Return Value

Returns a file wrapper for the appropriate document type, or nil if failure. When nil, error encapsulates the error information.

Discussion

Raises an NSRangeException if any part of range lies beyond the end of the receiver’s characters.

Availability

Available in OS X v10.4 and later.

Related Sample Code

TextEdit

Declared In

NSAttributedString.h

fontAttributesInRange:

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

- (NSDictionary *)fontAttributesInRange:(NSRange)aRange

Parameters

aRange: The range.

Return Value

A dictionary containing the font attributes for the range.

Discussion

The dictionary attributes are all those listed in “Standard Attributes”, except NSLinkAttributeName, NSParagraphStyleAttributeName, and NSAttachmentAttributeName.

Use this method to obtain font attributes that are to be copied or pasted with “copy font” operations.

Raises an NSRangeException if any part of aRange lies beyond the end of the receiver’s characters.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Popover

Declared In

NSAttributedString.h

initWithData:options:documentAttributes:error:

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

- (id)initWithData:(NSData *)data options:(NSDictionary *)options documentAttributes:(NSDictionary **)docAttributes error:(NSError **)error

Parameters

data: The data from which to create the string.
options: Specifies how the document should be loaded. Contains values described in “Option keys for importing documents.”
docAttributes: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.
error: An in-out parameter that returns an error if the method returns nil.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Discussion

If the options dictionary contains NSDocumentTypeDocumentOption, the document is treated as being in the specified format. If NSDocumentTypeDocumentOption is not specified, the method examines the document and loads it using whatever format it seems to contain.

Availability

Available in OS X v10.4 and later.

Related Sample Code

TextEdit

Declared In

NSAttributedString.h

initWithDocFormat:documentAttributes:

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

- (id)initWithDocFormat:(NSData *)data documentAttributes:(NSDictionary **)docAttributes

Parameters

data: The data from which to create the string.
docAttributes: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Availability

Available in OS X v10.3 and later.

Declared In

NSAttributedString.h

initWithHTML:baseURL:documentAttributes:

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

- (id)initWithHTML:(NSData *)data baseURL:(NSURL *)aURL documentAttributes:(NSDictionary **)docAttributes

Parameters

data: The data in HTML format from which to create the attributed string.
aURL: An NSURL that represents the base URL for all links within the HTML.
docAttributes: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

initWithHTML:documentAttributes:

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

- (id)initWithHTML:(NSData *)data documentAttributes:(NSDictionary **)docAttributes

Parameters

data: The data in HTML format from which to create the attributed string.
docAttributes: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

initWithHTML:options:documentAttributes:

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

- (id)initWithHTML:(NSData *)data options:(NSDictionary *)options documentAttributes:(NSDictionary **)dict

Parameters

data: The data in HTML format from which to create the attributed string.
options: Specifies how the document should be loaded. Contains values described in “Option keys for importing documents.”
dict: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Availability

Available in OS X v10.3 and later.

Declared In

NSAttributedString.h

initWithPath:documentAttributes:

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

- (id)initWithPath:(NSString *)path documentAttributes:(NSDictionary **)docAttributes

Parameters

path: The path to an RTF or RTFD file.
docAttributes: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Discussion

The contents of path will be examined to best load the file in whatever format it’s in. Filter services can be used to convert the file into a format recognized by Cocoa. Also returns by reference in docAttributes a dictionary containing document-level attributes described in “Document Attributes.” docAttributes may be NULL, in which case no document attributes are returned. Returns an initialized object, or nil if the file at path can’t be decoded.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSAttributedString.h

initWithRTF:documentAttributes:

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

- (id)initWithRTF:(NSData *)rtfData documentAttributes:(NSDictionary **)docAttributes

Parameters

rtfData: The data containing RTF content.
docAttributes: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Discussion

Also returns by reference in docAttributes a dictionary containing document-level attributes described in “Document Attributes.” docAttributes may be NULL, in which case no document attributes are returned. Returns an initialized object, or nil if rtfData can’t be decoded.

Availability

Available in OS X v10.0 and later.

Related Sample Code

iSpend

Declared In

NSAttributedString.h

initWithRTFD:documentAttributes:

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

- (id)initWithRTFD:(NSData *)rtfdData documentAttributes:(NSDictionary **)docAttributes

Parameters

rtfdData: The data containing the RTFD content.
docAttributes: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

initWithRTFDFileWrapper:documentAttributes:

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

- (id)initWithRTFDFileWrapper:(NSFileWrapper *)wrapper documentAttributes:(NSDictionary **)docAttributes

Parameters

wrapper: The NSFileWrapper containing the RTFD document.
docAttributes: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Discussion

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

initWithURL:documentAttributes:

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

- (id)initWithURL:(NSURL *)aURL documentAttributes:(NSDictionary **)docAttributes

Parameters

aURL: An NSURL object specifying the document to load.
docAttributes: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Discussion

The contents of aURL are examined to best load the file in whatever format it’s in. Filter services can be used to convert the file into a format recognized by Cocoa. Also returns by reference in docAttributes a dictionary containing document-level attributes described in “Document Attributes.” docAttributes may be NULL, in which case no document attributes are returned. Returns an initialized object, or nil if the file at path can’t be decoded.

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

initWithURL:options:documentAttributes:error:

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

- (id)initWithURL:(NSURL *)url options:(NSDictionary *)options documentAttributes:(NSDictionary **)docAttributes error:(NSError **)error

Parameters

url: An NSURL object specifying the document to load.
options: Specifies how the document should be loaded. Contains values described in “Option keys for importing documents.”
docAttributes: An in-out dictionary containing document-level attributes described in “Document Attributes.” May be NULL, in which case no document attributes are returned.
error: An in-out parameter that returns an error if the method returns nil.

Return Value

Returns an initialized object, or nil if the data can’t be decoded.

Discussion

Filter services can be used to convert the file into a format recognized by Cocoa. The options dictionary specifies how the document should be loaded and can contain the values described in “Option keys for importing documents.”

If NSDocumentTypeDocumentOption is specified, the document is treated as being in the specified format. If NSDocumentTypeDocumentOption is not specified, the method examines the document and loads it using whatever format it seems to contain.

Also returns by reference in dict a dictionary containing document-level attributes described in “Document Attributes.” The dict parameter may be nil, in which case no document attributes are returned. Returns an initialized object, or nil if the file at url can’t be decoded, after setting error to point to an NSError object that encapsulates the reason why the attributed string object could not be created.

Availability

Available in OS X v10.4 and later.

Related Sample Code

Declared In

NSAttributedString.h

itemNumberInTextList:atIndex:

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

- (NSInteger)itemNumberInTextList:(NSTextList *)list atIndex:(NSUInteger)location

Parameters

list: The text list.
location: The location of the item.

Return Value

Returns the index within the list.

Availability

Available in OS X v10.4 and later.

Declared In

NSAttributedString.h

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.

- (NSUInteger)lineBreakBeforeIndex:(NSUInteger)index withinRange:(NSRange)aRange

Parameters

index: The index in the attributed string.
aRange: The range.

Return Value

Returns the index of the closest character before index within aRange, that can be placed on a new line when laying out text. Returns NSNotFound if no line break is possible before index.

Discussion

Raises an NSRangeException if index or any part of aRange lies beyond the end of the receiver’s characters.

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

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.

- (NSUInteger)lineBreakByHyphenatingBeforeIndex:(NSUInteger)location withinRange:(NSRange)aRange

Parameters

location: The location in the attributed string.
aRange: The range.

Return Value

Returns the index of the closest character before index within aRange, that can be placed on a new line by hyphenating. Returns NSNotFound if no line break by hyphenation is possible before index.

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.

Raises an NSRangeException if index or any part of aRange lies beyond the end of the receiver’s characters.

Availability

Available in OS X v10.3 and later.

Declared In

NSAttributedString.h

nextWordFromIndex:forward:

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

- (NSUInteger)nextWordFromIndex:(NSUInteger)index forward:(BOOL)flag

Parameters

index: The index in the attribute string.
flag: YES if the search should be forward, otherwise NO.

Return Value

YES if this is the first character after index that begins a word; if flag is NO, it’s the first character before index that begins a word, whether index is located within a word or not.

Discussion

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.

Raises an NSRangeException if index lies beyond the end of the receiver’s characters.

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

rangeOfTextBlock:atIndex:

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

- (NSRange)rangeOfTextBlock:(NSTextBlock *)block atIndex:(NSUInteger)location

Parameters

block: The text block.
location: The location in the text block.

Return Value

The range of the text block containing the location.

Availability

Available in OS X v10.4 and later.

Related Sample Code

iSpend

Declared In

NSAttributedString.h

rangeOfTextList:atIndex:

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

- (NSRange)rangeOfTextList:(NSTextList *)list atIndex:(NSUInteger)location

Parameters

list: The text list.
location: The location in the text list.

Return Value

The range of the given text list containing the location.

Availability

Available in OS X v10.4 and later.

Declared In

NSAttributedString.h

rangeOfTextTable:atIndex:

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

- (NSRange)rangeOfTextTable:(NSTextTable *)table atIndex:(NSUInteger)location

Parameters

table: The text table.
location: The location.

Return Value

Returns the range of table that contains location.

Availability

Available in OS X v10.4 and later.

Related Sample Code

iSpend

Declared In

NSAttributedString.h

RTFDFileWrapperFromRange:documentAttributes:

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

- (NSFileWrapper *)RTFDFileWrapperFromRange:(NSRange)aRange documentAttributes:(NSDictionary *)docAttributes

Parameters

aRange: The range.
docAttributes: A required dictionary specifying the document attributes. The dictionary contains values from “Document Types” and must at least contain NSDocumentTypeDocumentAttribute. If there are no document-level attributes, dict can be nil.

Return Value

A file wrapper containing the RTFD data.

Discussion

The file wrapper also includes the document-level attributes in docAttributes, as explained in “RTF Files and Attributed Strings”.

Raises an NSRangeException if any part of aRange lies beyond the end of the receiver’s characters.

You can save the file wrapper using the NSFileWrapper method writeToFile:atomically:updateFilenames:.

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

RTFDFromRange:documentAttributes:

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

- (NSData *)RTFDFromRange:(NSRange)aRange documentAttributes:(NSDictionary *)docAttributes

Parameters

aRange: The range.
docAttributes: A required dictionary specifying the document attributes. The dictionary contains values from “Document Types” and must at least contain NSDocumentTypeDocumentAttribute. If there are no document-level attributes, dict can be nil.

Return Value

A data object containing the RTFD stream containing the characters and attributes.

Discussion

Writes the document-level attributes in docAttributes, as explained in “RTF Files and Attributed Strings”.

Raises an NSRangeException 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 the NSPasteboard method setData:forType:, with a second argument of NSRTFDPboardType.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSAttributedString.h

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.

- (NSData *)RTFFromRange:(NSRange)aRange documentAttributes:(NSDictionary *)docAttributes

Parameters

aRange: The range.
docAttributes: A required dictionary specifying the document attributes. The dictionary contains values from “Document Types” and must at least contain NSDocumentTypeDocumentAttribute. If there are no document-level attributes, dict can be nil.

Return Value

A data object containing an RTF stream for the attributed string..

Discussion

Writes the document-level attributes in docAttributes, as explained in “RTF Files and Attributed Strings”.

Raises an NSRangeException 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 the NSPasteboard method setData:forType:, with a second argument of NSRTFPboardType. Although this method strips attachments, it leaves the attachment characters in the text itself. The NSText method RTFFromRange:, on the other hand, does strip attachment characters when extracting RTF.

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

rulerAttributesInRange:

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

- (NSDictionary *)rulerAttributesInRange:(NSRange)aRange

Parameters

aRange: The range.

Return Value

A dictionary containing the ruler attributes in the range.

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.

Raises an NSRangeException if any part of aRange lies beyond the end of the receiver’s characters.

Availability

Available in OS X v10.0 and later.

Declared In

NSAttributedString.h

size

Returns the bounding box of the marks that the receiver draws.

- (NSSize)size

Return Value

Returns the size of the bounding box of the drawn attributed string.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSStringDrawing.h

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.

- (NSURL *)URLAtIndex:(NSUInteger)location effectiveRange:(NSRangePointer)effectiveRange

Parameters

location: The character index in the string at which the method checks for a link.
effectiveRange: The actual range covered by the link attribute or URL string, or of non-URL text if no apparent URL is found.

Return Value

The URL found at location.

Availability

Available in OS X v10.5 and later.

Declared In

NSAttributedString.h

Constants

Standard Attributes

Attributed strings support the following standard attributes for text. If the key is not in the dictionary, then use the default values described below.

NSString *NSFontAttributeName;
NSString *NSParagraphStyleAttributeName;
NSString *NSForegroundColorAttributeName;
NSString *NSUnderlineStyleAttributeName;
NSString *NSSuperscriptAttributeName;
NSString *NSBackgroundColorAttributeName;
NSString *NSAttachmentAttributeName;
NSString *NSLigatureAttributeName;
NSString *NSBaselineOffsetAttributeName;
NSString *NSKernAttributeName;
NSString *NSLinkAttributeName;
NSString *NSStrokeWidthAttributeName;
NSString *NSStrokeColorAttributeName;
NSString *NSUnderlineColorAttributeName;
NSString *NSStrikethroughStyleAttributeName;
NSString *NSStrikethroughColorAttributeName;
NSString *NSShadowAttributeName;
NSString *NSObliquenessAttributeName;
NSString *NSExpansionAttributeName;
NSString *NSCursorAttributeName;
NSString *NSToolTipAttributeName;
NSString *NSMarkedClauseSegmentAttributeName;
NSString *NSWritingDirectionAttributeName;
NSString *NSVerticalGlyphFormAttributeName;
NSString *NSTextAlternativesAttributeName;

Constants

NSFontAttributeName

NSFont

Default Helvetica 12-point

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSParagraphStyleAttributeName

NSParagraphStyle

Default as returned by the NSParagraphStyle method defaultParagraphStyle

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSForegroundColorAttributeName

NSColor

Default blackColor

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSUnderlineStyleAttributeName

NSNumber containing integer

Default 0, no underline. See “Underlining Patterns”, “Underlining Styles”, and “Underline Masks” for mask values.

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSSuperscriptAttributeName

NSNumber containing integer

Default 0

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSBackgroundColorAttributeName

NSColor

Default nil, no background

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSAttachmentAttributeName

NSTextAttachment

Default nil, no attachment

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSLigatureAttributeName

NSNumber containing integer

Default 1, standard ligatures; 0, no ligatures; 2, all ligatures

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSBaselineOffsetAttributeName

NSNumber containing floating point value, as points offset from baseline

Default 0.0

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSKernAttributeName

NSNumber containing floating point value, as points by which to modify default kerning

Default nil, use default kerning specified in font file; 0.0, kerning off; non-zero, points by which to modify default kerning

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSLinkAttributeName

NSURL (preferred) or NSString

Default nil, no link

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSStrokeWidthAttributeName

NSNumber containing floating point value, as percent of font point size

Default 0, no stroke; positive, stroke alone; negative, stroke and fill (a typical value for outlined text would be 3.0)

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSStrokeColorAttributeName

NSColor

Default nil, same as foreground color

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSUnderlineColorAttributeName

NSColor

Default nil, same as foreground color

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSStrikethroughStyleAttributeName

NSNumber containing integer

Default 0, no strikethrough. See “Underlining Patterns”, “Underlining Styles”, and “Underline Masks” for mask values.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSStrikethroughColorAttributeName

NSColor

Default nil, same as foreground color

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSShadowAttributeName

NSShadow

Default nil, no shadow

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSObliquenessAttributeName

NSNumber containing floating point value, as skew to be applied to glyphs

Default 0.0, no skew

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSExpansionAttributeName

NSNumber containing floating point value, as log of expansion factor to be applied to glyphs

Default 0.0, no expansion

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSCursorAttributeName

NSCursor

Default as returned by the NSCursor method IBeamCursor

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSToolTipAttributeName

NSString

Default nil, no tooltip

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSMarkedClauseSegmentAttributeName

NSNumber containing an integer, as an index in marked text indicating clause segments

Available in OS X v10.5 and later.

Declared in NSAttributedString.h.

NSWritingDirectionAttributeName

An NSArray of NSNumber objects.

This attribute provides a means to override the default bidirectional text algorithm, equivalent to using the Unicode bidi control characters LRE, RLE, LRO, or RLO paired with PDF, but as a higher-level attribute. (See Unicode Standard Annex #9 for information about the Unicode bidi formatting codes.) The NSWritingDirectionAttributeName constant is a character-level attribute that provides a higher-level alternative to the inclusion of explicit bidirectional control characters in text. It is the NSAttributedString equivalent of the HTML markup using bdo element with the dir attribute.

The value of NSWritingDirectionAttributeName is an NSArray of NSNumber objects. The array represents nested embeddings or overrides, in order from outermost to innermost.

The values of the NSNumber objects should be 0, 1, 2, or 3, for LRE, RLE, LRO, or RLO respectively, and combinations of NSWritingDirectionLeftToRight and NSWritingDirectionRightToLeft with NSTextWritingDirectionEmbedding or NSTextWritingDirectionOverride, as shown in Table 1.

**Table 1** Values of `NSWritingDirectionAttributeName` and equivalent markup
Array NSNumber Values	Unicode Control Characters	NSWritingDirection Constants
`0`	`LRE`	`NSWritingDirectionLeftToRight \| NSTextWritingDirectionEmbedding`
`1`	`RLE`	`NSWritingDirectionRightToLeft \| NSTextWritingDirectionEmbedding`
`2`	`LRO`	`NSWritingDirectionLeftToRight \| NSTextWritingDirectionOverride`
`3`	`RLO`	`NSWritingDirectionRightToLeft \| NSTextWritingDirectionOverride`

Available in OS X v10.6 and later.

Declared in NSAttributedString.h.

NSVerticalGlyphFormAttributeName

An NSNumber containing an integer value, 0 means horizontal text and 1 indicates vertical text. If no value specified, it's interpreted to determine the setting based on higher-level vertical orientation settings such as NSTextLayoutOrientation . The behavior for any other value is undefined.

Available in OS X v10.7 and later.

Declared in NSAttributedString.h.

NSTextAlternativesAttributeName

An NSTextAlternatives object. Used primarily as a temporary attribute, with primaryString equal to the substring for the range to which it is attached, and alternativeStrings representing alternatives for that string that may be presented to the user.

Available in OS X v10.8 and later.

Declared in NSAttributedString.h.

Underlining Styles

These constants define underlining style values for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

enum {
   NSUnderlineStyleNone   = 0x00,
   NSUnderlineStyleSingle   = 0x01,
   NSUnderlineStyleThick   = 0x02,
   NSUnderlineStyleDouble   = 0x09
};

Constants

NSUnderlineStyleNone

Do not draw an underline.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSUnderlineStyleSingle

Draw an underline consisting of a single line.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSUnderlineStyleThick

Draw an underline consisting of a thick line.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSUnderlineStyleDouble

Draw an underline consisting of a double line.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

Discussion

See also “Underline Masks” and “Underlining Patterns”. The style, pattern, and optionally by-word mask are OR'd together to produce the value for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

Declared In

NSAttributedString.h

Underlining Patterns

These constants define underlining pattern values for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

enum {
   NSUnderlinePatternSolid   = 0x0000,
   NSUnderlinePatternDot   = 0x0100,
   NSUnderlinePatternDash   = 0x0200,
   NSUnderlinePatternDashDot   = 0x0300,
   NSUnderlinePatternDashDotDot  = 0x0400
};

Constants

NSUnderlinePatternSolid

Draw a solid underline.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSUnderlinePatternDot

Draw an underline using a pattern of dots.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSUnderlinePatternDash

Draw an underline using a pattern of dashes.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSUnderlinePatternDashDot

Draw an underline using a pattern of alternating dashes and dots.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSUnderlinePatternDashDotDot

Draw an underline using a pattern of a dash followed by two dots.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

Discussion

See also “Underline Masks” and “Underlining Styles”. The style, pattern, and optionally by-word mask are OR'd together to produce the value for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

Deprecated Underlining Styles

Deprecated constants previously used for underline style. (Deprecated. See “Underlining Patterns” for the correct replacements.)

enum {
   NSNoUnderlineStyle = 0,
   NSSingleUnderlineStyle
};
NSUInteger NSUnderlineStrikethroughMask;

Constants

NSNoUnderlineStyle: Deprecated. See “Underlining Patterns” for the correct replacements.
NSSingleUnderlineStyle: Deprecated. See “Underlining Patterns” for the correct replacements.

Underline Masks

This constant defines the underlining style for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

unsigned NSUnderlineByWordMask;

Constants

NSUnderlineByWordMask

Draw the underline only underneath words, not underneath whitespace.

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

Discussion

Use this constant with the desired underline style to create the given effect. For example, to get a thick underline only underneath words, set NSUnderlineStyleAttribute to (NSUnderlineStyleThick | NSUnderlineByWordMask). Also see “Underlining Styles” and “Underlining Patterns.”

Declared In

NSAttributedString.h

Glyph Info Attribute

This object provides a means to override the standard glyph generation.

NSString *NSGlyphInfoAttributeName;

Constants

NSGlyphInfoAttributeName

The name of an NSGlyphInfo object.

NSLayoutManager assigns the glyph specified by this glyph info to the entire attribute range, provided that its contents match the specified base string, and that the specified glyph is available in the font specified by NSFontAttributeName.

Available in OS X v10.2 and later.

Declared in NSAttributedString.h.

Declared In

NSAttributedString.h

Character Shape Attribute

The character shape feature type (kCharacterShapeType) is used when a single font contains different appearances for the same character shape, and these shapes are not traditionally treated as swashes. It is needed for languages such as Chinese that have both traditional and simplified character sets.

NSString *NSCharacterShapeAttributeName;

Constants

NSCharacterShapeAttributeName

An integer value. The value is interpreted as Apple Type Services kCharacterShapeType selector + 1.

The default value is 0 (disable). 1 is kTraditionalCharactersSelector, and so on. Refer to <ATS/SFNTLayoutTypes.h> and “Font Features” in ATSUI Programming Guide for additional information.

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

Declared In

NSAttributedString.h

Document Types

The following values can be returned for the NSDocumentTypeDocumentAttribute key in the document attributes dictionary.

NSString *NSPlainTextDocumentType;
NSString *NSRTFTextDocumentType;
NSString *NSRTFDTextDocumentType;
NSString *NSMacSimpleTextDocumentType;
NSString *NSHTMLTextDocumentType;
NSString *NSDocFormatTextDocumentType;
NSString *NSWordMLTextDocumentType;
NSString *NSOfficeOpenXMLTextDocumentType;
NSString *NSWebArchiveTextDocumentType;
NSString *NSOpenDocumentTextDocumentType;

Constants

NSPlainTextDocumentType

Plain text document.

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSRTFTextDocumentType

Rich text format document.

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSRTFDTextDocumentType

Rich text format with attachments document.

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSMacSimpleTextDocumentType

Macintosh SimpleText document.

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSHTMLTextDocumentType

Hypertext Markup Language (HTML) document.

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSDocFormatTextDocumentType

Microsoft Word document.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSWordMLTextDocumentType

Microsoft Word XML (WordML schema) document.

Available in OS X v10.3 and later.

Declared in NSAttributedString.h.

NSWebArchiveTextDocumentType

Web Kit WebArchive document.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSOfficeOpenXMLTextDocumentType

ECMA Office Open XML text document format.

Available in OS X v10.5 and later.

Declared in NSAttributedString.h.

NSOpenDocumentTextDocumentType

OASIS Open Document text document format.

Available in OS X v10.5 and later.

Declared in NSAttributedString.h.

Discussion

Declared In

NSAttributedString.h

Document Attributes

The init... methods can return a dictionary with the following document-wide attributes (attribute identifiers available on OS X v10.4 and later; use actual string value keys for earlier systems):

NSString *NSAuthorDocumentAttribute;
NSString *NSBackgroundColorDocumentAttribute;
NSString *NSBottomMarginDocumentAttribute;
NSString *NSCharacterEncodingDocumentAttribute;
NSString *NSCategoryDocumentAttribute;
NSString *NSCocoaVersionDocumentAttribute;
NSString *NSCommentDocumentAttribute;
NSString *NSCompanyDocumentAttribute;
NSString *NSConvertedDocumentAttribute;
NSString *NSCopyrightDocumentAttribute;
NSString *NSCreationTimeDocumentAttribute;
NSString *NSDefaultTabIntervalDocumentAttribute;
NSString *NSDocumentTypeDocumentAttribute;
NSString *NSEditorDocumentAttribute;
NSString *NSFileTypeDocumentAttribute;
NSString *NSFileTypeDocumentOption;
NSString *NSHyphenationFactorDocumentAttribute;
NSString *NSKeywordsDocumentAttribute;
NSString *NSLeftMarginDocumentAttribute;
NSString *NSManagerDocumentAttribute;
NSString *NSModificationTimeDocumentAttribute;
NSString *NSPaperSizeDocumentAttribute;
NSString *NSReadOnlyDocumentAttribute;
NSString *NSRightMarginDocumentAttribute;
NSString *NSSubjectDocumentAttribute;
NSString *NSTitleDocumentAttribute;
NSString *NSUsesScreenFontsDocumentAttribute;
NSString *NSTopMarginDocumentAttribute;
NSString *NSViewModeDocumentAttribute;
NSString *NSViewSizeDocumentAttribute;
NSString *NSViewZoomDocumentAttribute;

Constants

NSPaperSizeDocumentAttribute

NSValue, containing NSSize.

OS X v10.3 and earlier string constant is @"PaperSize".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSLeftMarginDocumentAttribute

NSNumber, containing a float, in points.

OS X v10.3 and earlier string constant is @"LeftMargin".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSRightMarginDocumentAttribute

NSNumber, containing a float, in points.

OS X v10.3 and earlier string constant is @"RightMargin".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSTopMarginDocumentAttribute

NSNumber, containing a float, in points.

OS X v10.3 and earlier string constant is @"TopMargin".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSBottomMarginDocumentAttribute

NSNumber, containing a float, in points.

OS X v10.3 and earlier string constant is @"BottomMargin".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSHyphenationFactorDocumentAttribute

NSNumber, containing a float; 0 = off, 1 = full hyphenation.

OS X v10.3 and earlier string constant is @"HyphenationFactor".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSDocumentTypeDocumentAttribute

How the document was interpreted; one of the values in “Document Types.”

OS X v10.3 and earlier string constant is @"DocumentType".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSCharacterEncodingDocumentAttribute

NSNumber, containing an int specifying the NSStringEncoding for the file; for reading and writing plain text files and writing HTML; default for plain text is the default encoding; default for HTML is UTF-8.

OS X v10.3 and earlier string constant is @"CharacterEncoding".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSViewSizeDocumentAttribute

NSValue, containing NSSize.

OS X v10.3 and earlier string constant is @"ViewSize".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSViewZoomDocumentAttribute

OS X v10.3 and earlier string constant is @"ViewZoom".

NSValue, containing a float; 100 = 100% zoom.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSViewModeDocumentAttribute

NSValue, containing an int; 0 = normal; 1 = page layout (use value of @"PaperSize").

OS X v10.3 and earlier string constant is @"ViewMode".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSBackgroundColorDocumentAttribute

NSColor, representing the document-wide page background color.

OS X v10.3 and earlier string constant is @"BackgroundColor".

For applications linked on versions prior to OS X v10.5, HTML import sets the NSBackgroundColorDocumentAttribute to [NSColor whiteColor] in cases in which the HTML does not specify a background color. For applications linked on OS X v10.5 and later, no NSBackgroundColorDocumentAttribute is set in these cases.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSCocoaVersionDocumentAttribute

NSNumber, containing a float. For RTF files only, stores the version of Cocoa with which the file was created. Absence of this value indicates RTF file not created by Cocoa or its predecessors.

Values less than 100 are pre–OS X; 100 is OS X v10.0 or v10.1; 102 is OS X v10.2 and 10.3; values greater than 102 correspond to values of NSAppKitVersionNumber on OS X v10.4 and later.

OS X v10.3 and earlier string constant is @"CocoaRTFVersion".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSReadOnlyDocumentAttribute

NSNumber, containing int. If missing or 0 or negative, not read only; 1 or more, read only.

Note that this has nothing to do with the file system protection on the file, but instead can affect how the file should be displayed to the user.

OS X v10.3 and earlier string constant is @"ReadOnly".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSConvertedDocumentAttribute

NSNumber, containing an int. Indicates whether the file was converted by a filter service.

If missing or 0, the file was originally in the format specified by document type. If negative, the file was originally in the format specified by document type, but the conversion to NSAttributedString may have been lossy. If 1 or more, it was converted to this type by a filter service.

OS X v10.3 and earlier string constant is @"Converted".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSDefaultTabIntervalDocumentAttribute

NSNumber containing a float. Represents the document-wide default tab stop interval.

OS X v10.3 and earlier string constant is @"DefaultTabInterval".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSTitleDocumentAttribute

NSString containing document title.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSUsesScreenFontsDocumentAttribute

A boolean NSNumber; this attribute corresponds to the NSLayoutManager usesScreenFonts method; if absent, follows the system default setting

Available in OS X v10.8 and later.

Declared in NSAttributedString.h.

NSCompanyDocumentAttribute

NSString containing company or organization name.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSCopyrightDocumentAttribute

NSString containing document copyright info.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSSubjectDocumentAttribute

NSString containing subject of document.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSAuthorDocumentAttribute

NSString containing author name.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSKeywordsDocumentAttribute

NSArray of NSString, containing keywords.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSCommentDocumentAttribute

NSString containing document comments.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSEditorDocumentAttribute

NSString containing name of person who last edited the document.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSCreationTimeDocumentAttribute

NSDate containing the creation date of the document; note that this is not the file system creation date of the file, but of the document.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSModificationTimeDocumentAttribute

NSDate containing the modification date of the document contents.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSManagerDocumentAttribute

NSString containing the name of the author's manager.

Available in OS X v10.6 and later.

Declared in NSAttributedString.h.

NSCategoryDocumentAttribute

NSString containing the document’s category.

Available in OS X v10.6 and later.

Declared in NSAttributedString.h.

NSFileTypeDocumentAttribute

NSString indicating which document type was used to interpret the document, specified as a UTI; for reading, this is available along with NSDocumentTypeDocumentAttribute, but for writing the two are mutually exclusive.

Available in OS X v10.6 and later.

Declared in NSAttributedString.h.

NSFileTypeDocumentOption

NSString indicating a document type to be forced when loading the document, specified as a UTI string; mutually exclusive with NSDocumentTypeDocumentOption.

Available in OS X v10.6 and later.

Declared in NSAttributedString.h.

Attributes for generating HTML

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

NSString *NSExcludedElementsDocumentAttribute;
NSString *NSTextEncodingNameDocumentAttribute;
NSString *NSPrefixSpacesDocumentAttribute;

Constants

NSExcludedElementsDocumentAttribute

An NSArray object containing NSString objects, representing HTML elements not to be used in generated HTML.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSTextEncodingNameDocumentAttribute

An NSString object containing the name, IANA or otherwise, of a text encoding to be used; mutually exclusive with NSCharacterEncodingDocumentAttribute.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSPrefixSpacesDocumentAttribute

An NSNumber containing an integer (default 0) representing the number of spaces per level by which to indent certain nested HTML elements.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

Discussion

NSExcludedElementsDocumentAttribute allows control over the tags used. The recognized values in the NSExcludedElementsDocumentAttribute array are (case-insensitive) HTML tags, plus DOCTYPE (representing a doctype declaration) and XML (representing an XML declaration). By default, if this attribute is not present, the excluded elements will be those deprecated in HTML 4 (APPLET, BASEFONT, CENTER, DIR, FONT, ISINDEX, MENU, S, STRIKE, and U) plus XML. If XML is on the list, HTML forms are used; if XML is not on the list, XHTML forms are used where there is a distinction. Either NSCharacterEncodingDocumentAttribute or NSTextEncodingNameDocumentAttribute may be used to control the encoding used for generated HTML; character entities are used for characters not representable in the specified encoding. NSPrefixSpacesDocumentAttribute allows some control over formatting.

Declared In

NSAttributedString.h

Option keys for importing documents

These option keys are recognized for importing documents using initWithData:options:documentAttributes:error:, initWithHTML:options:documentAttributes:, initWithURL:options:documentAttributes:error:, or the readFrom... methods (such as readFromData:options:documentAttributes:) implemented by NSMutableAttributedString.

NSString *NSBaseURLDocumentOption;
NSString *NSCharacterEncodingDocumentOption;
NSString *NSDefaultAttributesDocumentOption;
NSString *NSDocumentTypeDocumentOption;
NSString *NSTextEncodingNameDocumentOption;
NSString *NSTextSizeMultiplierDocumentOption;
NSString *NSTimeoutDocumentOption;
NSString *NSWebPreferencesDocumentOption;
NSString *NSWebResourceLoadDelegateDocumentOption;

Constants

NSCharacterEncodingDocumentOption

For plain text documents; NSNumber containing the unsigned int NSStringEncoding to override any encoding specified in an HTML document. Previous string constant was @"CharacterEncoding".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSBaseURLDocumentOption

For HTML documents; NSURL containing base URL. Previous string constant was @"BaseURL"

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSDefaultAttributesDocumentOption

For plain text documents; NSDictionary containing attributes to be applied to plain files. Previous string constant was @"DefaultAttributes".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSDocumentTypeDocumentOption

One of the document types described in “Document Types,” indicating a document type to be forced when loading the document. Previous string constant was @"DocumentType".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSTextEncodingNameDocumentOption

NSString containing the name, IANA or otherwise, of a text encoding to override any encoding specified in an HTML document. Mutually exclusive with @"CharacterEncoding". Previous string constant was @"TextEncodingName".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSTimeoutDocumentOption

NSNumber containing float. Time in seconds to wait for a document to finish loading. Previous string constant was @"Timeout".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSWebPreferencesDocumentOption

WebPreferences; for HTML only, specifies a WebPreferences object. If not present, a default set of preferences is used. Previous string constant was @"WebPreferences".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSWebResourceLoadDelegateDocumentOption

NSObject; for HTML only, specifies an object to serve as the web resource loading delegate.

If not present, a default delegate is used that permits the loading of subsidiary resources but does not respond to authentication challenges. Previous string constant was @"WebResourceLoadDelegate".

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

NSTextSizeMultiplierDocumentOption

Specifies a scale factor for font sizes.. NSNumber containing float, default 1.0; for HTML only, corresponding to WebView's textSizeMultiplier.

There is no textual equivalent for OS X v10.3.

Available in OS X v10.4 and later.

Declared in NSAttributedString.h.

Discussion

In OS X v10.3, the options key @"UseWebKit" specifies that WebKit–based HTML importing be used (and must be specified for the other options to be recognized). In OS X v10.4 and later, WebKit is always used for HTML documents, and all of the options except @"UseWebKit" are recognized (attribute identifiers are available on OS X v10.4 and later; use actual string value keys for OS X v10.3):

NSSpellingStateAttributeName

This constant is used as, and recognized only as, a temporary attribute. It indicates that spelling and/or grammar indicators should be shown for the specified characters.

NSString *NSSpellingStateAttributeName;

Constants

NSSpellingStateAttributeName

An integer value. Defaults to 0, indicating no grammar or spelling error. See “Underlining Patterns” for possible values.

This key is available in OS X v10.2 and later, but its interpretation changed in OS X v10.5. Previously, any non-zero value caused the spelling indicator to be displayed. For OS X v10.5 and later, the (integer) value is treated as being composed of the spelling and grammar flags. See “NSUnderlineStrikethroughMask” for possible values.

Available in OS X v10.5 and later.

Declared in NSAttributedString.h.

NSTextLayoutSectionsAttribute

This constant specifies the layout orientation section attribute for persistence.

NSString *NSTextLayoutSectionsAttribute;

Constants

NSTextLayoutSectionsAttribute

An NSArray containing NSDictionary objects. Each dictionary describes a layout orientation section. The dictionary can have two attributes: NSTextLayoutSectionOrientation and NSTextLayoutSectionRange. When there is a gap between sections, it’s assumed to have NSTextLayoutOrientationHorizontal.

Available in OS X v10.7 and later.

Declared in NSAttributedString.h.

NSLayoutOrientationSectionsAttribute

These constants are used as by the NSLayoutOrientationSectionsAttribute.

NSString *NSTextLayoutSectionOrientation;
NSString *NSTextLayoutSectionRange;

Constants

NSTextLayoutSectionOrientation

An NSNumber containing an NSTextLayoutOrientation value. The default value is NSTextLayoutOrientationHorizontal.

Available in OS X v10.7 and later.

Declared in NSAttributedString.h.

NSTextLayoutSectionRange

An NSValue containing an NSRange representing a character range. The default value is a range covering the entire string.

Available in OS X v10.7 and later.

Declared in NSAttributedString.h.

NSSpellingStateAttributeName Flags

These constants control the display of the spelling and grammar indicators on text, highlighting portions of the text that are flagged for spelling or grammar issues. These regions are denoted by a temporary attribute on the layout manager, using the NSSpellingStateAttributeName key.

   
enum {
   NSSpellingStateSpellingFlag = (1 << 0),
   NSSpellingStateGrammarFlag  = (1 << 1)
};

Constants

NSSpellingStateSpellingFlag

Flag for spelling issues.

Available in OS X v10.5 and later.

Declared in NSAttributedString.h.

NSSpellingStateGrammarFlag

Flag for grammar issues.

Available in OS X v10.5 and later.

Declared in NSAttributedString.h.

NSUnderlineStrikethroughMask

These constants define the underline mask. (Deprecated. These constants have been deprecated. Use the “Standard Attributes” values instead.)

enum {
   NSNoUnderlineStyle = 0,
   NSSingleUnderlineStyle
};
NSUInteger NSUnderlineStrikethroughMask;

Constants

NSNoUnderlineStyle

No underline style.

Available in OS X v10.0 and later.

Declared in NSAttributedString.h.

NSSingleUnderlineStyle

Single underline style.

Available in OS X v10.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.

NSAttributedString Application Kit Additions Reference

Overview

Tasks

Creating an NSAttributedString

Retrieving Font Attribute Information

Calculating Linguistic Units

Calculating Ranges

Generating Data

Drawing the String

Getting the Bounding Rectangle of Rendered Strings

Testing String Data Sources

Deprecated Methods

Class Methods

attributedStringWithAttachment:

Parameters

Return Value

Availability

Related Sample Code

Declared In

textTypes

Return Value

Discussion

Availability

Declared In

textUnfilteredTypes

Return Value

Discussion

Availability

Declared In

Instance Methods

boundingRectWithSize:options:

Parameters

Return Value

Discussion

Availability

See Also

Declared In

containsAttachments

Return Value

Discussion

Availability

Declared In

dataFromRange:documentAttributes:error:

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

docFormatFromRange:documentAttributes:

Parameters

Return Value

Discussion

Availability

Declared In

doubleClickAtIndex:

Parameters

Return Value

Discussion

Availability

See Also

Declared In

drawAtPoint:

Parameters

Discussion

Availability

See Also

Related Sample Code

Declared In

drawInRect:

Parameters

Discussion

Availability

See Also

Related Sample Code

Declared In

drawWithRect:options:

Parameters

Discussion