Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Objective-C

Table of Contents

NSAttributedString Additions


Inherits from:
NSObject
Declared in:
AppKit/NSAttributedString.h
AppKit/NSStringDrawing.h
AppKit/NSTextAttachment.h




Class Description


The Application Kit extends the Foundation Kit's NSAttributedString class by adding:




Method Types


Creating an NSAttributedString
+ attributedStringWithAttachment:
- initWithHTML:documentAttributes:
- initWithHTML:baseURL:documentAttributes:
- initWithPath:documentAttributes:
- initWithRTF:documentAttributes:
- initWithRTFD:documentAttributes:
- initWithRTFDFileWrapper:documentAttributes:
- initWithURL:documentAttributes:
Retrieving font attribute information
- containsAttachments
- fontAttributesInRange:
- rulerAttributesInRange:
Calculating linguistic units
- doubleClickAtIndex:
- lineBreakBeforeIndex:withinRange:
- nextWordFromIndex:forward:
Generating RTF data
- RTFFromRange:documentAttributes:
- RTFDFromRange:documentAttributes:
- RTFDFileWrapperFromRange:documentAttributes:
Drawing the string
- drawAtPoint:
- drawInRect:
- size


Class Methods



attributedStringWithAttachment:

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

Creates an attributed string with an attachment.


Instance Methods



containsAttachments

- (BOOL)containsAttachments

Returns YES if the receiver contains any attachment attributes, NO otherwise. This method checks only for attachment attributes, not for NSAttachmentCharacter.

doubleClickAtIndex:

- (NSRange)doubleClickAtIndex:(unsigned)index

Returns the range of characters that form a word (or other linguistic unit) surrounding index, taking language characteristics into account. Raises an NSRangeException if index lies beyond the end of the receiver's characters.

See Also: - nextWordFromIndex:forward:



drawAtPoint:

- (void)drawAtPoint:(NSPoint)point

Draws the receiver with its font and other display attributes at point in the currently focused NSView. Text is drawn in such a way that the upper left corner of its bounding box lies at point, regardless of the line sweep direction or whether the NSView is flipped.

Don't invoke this method while no NSView is focused.

See Also: - lockFocus (NSView), - size, - drawInRect:



drawInRect:

- (void)drawInRect:(NSRect)rect

Draws the receiver with its font and other display attributes within rect in the currently focused NSView, clipping the drawing to this rectangle. 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.

Don't invoke this method while no NSView is focused.

See Also: - lockFocus (NSView), - drawAtPoint:



fontAttributesInRange:

- (NSDictionary *)fontAttributesInRange:(NSRange)aRange

Returns the font attributes in effect for the character at aRange.location. Font attributes are all those listed under "Accessing Attributes" in the class cluster description except 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.

See Also: - rulerAttributesInRange:



initWithHTML:documentAttributes:

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

Initializes and returns a new NSAttributedString from HTML contained in data. Also returns by reference in docAttributes a dictionary containing document-level attributes:
Key
Title
BaseURL
BackgroundImageURL
BackgroundColor
TextColor
LinkColor
ActiveLinkColor
VisitedLinkColor
LeftMargin
TopMargin

The parameter docAttributes can be NULL, in which case no document attributes are returned. Returns nil if data can't be decoded.



initWithHTML:baseURL:documentAttributes:

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

Description forthcoming.

initWithPath:documentAttributes:

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

Initializes a new NSAttributedString from RTF or RTFD data contained in the file at path. Also returns by reference in docAttributes a dictionary containing document-level attributes, as listed in the class cluster description under "Accessing Attributes" . docAttributes may be NULL, in which case no document attributes are returned. Returns self, or nil if the file at path can't be decoded.

initWithRTF:documentAttributes:

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

Initializes a new NSAttributedString by decoding the stream of RTF commands and data contained in rtfData. Also returns by reference in docAttributes a dictionary containing document-level attributes, as listed in the class cluster description under the "RTF Document Attributes" heading. docAttributes may be NULL, in which case no document attributes are returned. Returns self, or nil if rtfData can't be decoded.

initWithRTFD:documentAttributes:

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

Initializes a new NSAttributedString by decoding the stream of RTFD commands and data contained in rtfdData. Also returns by reference in docAttributes a dictionary containing document-level attributes, as listed in the class cluster description under the "RTF Document Attributes" heading. docAttributes may be NULL, in which case no document attributes are returned. Returns self, or nil if rtfData can't be decoded.

initWithRTFDFileWrapper:documentAttributes:

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

Initializes a new NSAttributedString from wrapper , an NSFileWrapper object containing an RTFD document. Also returns by reference in docAttributes a dictionary containing document-level attributes, as listed in the class cluster description under ""RTF Document Attributes" . docAttributes may be NULL, in which case no document attributes are returned. Returns self, or nil if wrapper can't be interpreted as an RTFD document.

initWithURL:documentAttributes:

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

Description forthcoming.

lineBreakBeforeIndex:withinRange:

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

Returns the index of the closest character before index and within aRange that can be placed on a new line when laying out text. 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 NSNotFound if no line break is possible before index.Raises an NSRangeException if index or any part of aRange lies beyond the end of the receiver's characters.

nextWordFromIndex:forward:

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

Returns the index of the first character of the word after or before index. If flag is YES, 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. 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.

See Also: - lineBreakBeforeIndex:withinRange:



RTFFromRange:documentAttributes:

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

Returns an NSData object that contains an RTF stream corresponding to the characters and attributes within aRange, omitting all attachment attributes. Also writes the document-level attributes in docAttributes, as explained in the class cluster description under "RTF Document Attributes" . If there are no document-level attributes, docAttributes can be nil. 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 NSPasteboard's setData:forType:, with a second argument of NSRTFPboardType.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: - RTFDFromRange:documentAttributes:, - RTFDFileWrapperFromRange:documentAttributes:



RTFDFromRange:documentAttributes:

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

Returns an NSData object that contains an RTFD stream corresponding to the characters and attributes within aRange. Also writes the document-level attributes in docAttributes, as explained in the class cluster description under "RTF Document Attributes" . If there are no document-level attributes, docAttributes can be nil. 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 NSPasteboard's setData:forType:, with a second argument of NSRTFDPboardType.

See Also: - RTFFromRange:documentAttributes:, - RTFDFileWrapperFromRange:documentAttributes:



RTFDFileWrapperFromRange:documentAttributes:

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

Returns an NSFileWrapper object that contains an RTFD document corresponding to the characters and attributes within aRange. The file wrapper also includes the document-level attributes in docAttributes, as explained in the class cluster description under "RTF Document Attributes" . If there are no document-level attributes, docAttributes can be nil. Raises an NSRangeException if any part of aRange lies beyond the end of the receiver's characters.You can save the file wrapper using NSFileWrapper's writeToFile:atomically:updateFilenames:.

See Also: - RTFFromRange:documentAttributes:, - RTFDFromRange:documentAttributes:



rulerAttributesInRange:

- (NSDictionary *)rulerAttributesInRange:(NSRange)range

Returns the ruler (paragraph) attributes in effect for the characters within aRange. 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.

See Also: - fontAttributesInRange:



size

- (NSSize)size

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

See Also: - drawAtPoint:, - drawInRect:




Table of Contents