NSMutableAttributedString Additions Reference

Inherits from
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSAttributedString.h
NSTextAttachment.h

Overview

Additions to the NSMutableAttributedString class primarily involve setting graphical attributes, such as font, super- or subscripting, and alignment, and making these attributes consistent after changes.

Tasks

Changing Attributes

Updating Attachment Contents

Fixing Attributes After Changes

Reading Content

Instance Methods

applyFontTraits:range:

Applies the font attributes specified by mask to the characters in aRange.

- (void)applyFontTraits:(NSFontTraitMask)mask range:(NSRange)aRange
Discussion

See the NSFontManager class specification for a description of the font traits available. 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

fixAttachmentAttributeInRange:

Cleans up attachment attributes in aRange, removing all attachment attributes assigned to characters other than NSAttachmentCharacter.

- (void)fixAttachmentAttributeInRange:(NSRange)aRange
Discussion

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

fixAttributesInRange:

Invokes the other fix... methods, allowing you to clean up an attributed string with a single message.

- (void)fixAttributesInRange:(NSRange)aRange
Discussion

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

NSTextStorage subclasses that return YES from the fixesAttributesLazily method should avoid directly calling fixAttributesInRange: or else bracket such calls with beginEditing and endEditing messages.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSAttributedString.h

fixFontAttributeInRange:

Fixes the font attribute in aRange, assigning default fonts to characters with illegal fonts for their scripts and otherwise correcting font attribute assignments.

- (void)fixFontAttributeInRange:(NSRange)aRange
Discussion

For example, Kanji characters assigned a Latin font are reassigned an appropriate Kanji font. 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

fixParagraphStyleAttributeInRange:

Fixes the paragraph style attributes in aRange, assigning the first paragraph style attribute value in each paragraph to all characters of the paragraph.

- (void)fixParagraphStyleAttributeInRange:(NSRange)aRange
Discussion

This method extends the range as needed to cover the last paragraph partially contained. A paragraph is delimited by any of these characters, the longest possible sequence being preferred to any shorter:

  • U+000D (\r or CR)

  • U+000A (\n or LF)

  • U+2029 (Unicode paragraph separator) \r\n, in that order (also known as CRLF)

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

readFromData:options:documentAttributes:

Sets the contents of the receiver from the stream at data.

- (BOOL)readFromData:(NSData *)data options:(NSDictionary *)options documentAttributes:(NSDictionary **)dict
Discussion

options can contain one of the values described in the “Constants” section of NSAttributedString AppKit Additions Reference ("Option keys for importing documents").

On return, the documentAttributes dictionary (if provided) contains the various keys described in the “Constants” section of NSAttributedString AppKit Additions Reference.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSAttributedString.h

readFromData:options:documentAttributes:error:

Sets the contents of the receiver from the stream at data.

- (BOOL)readFromData:(NSData *)data options:(NSDictionary *)opts documentAttributes:(NSDictionary **)dict error:(NSError **)error
Discussion

opts can contain one of the values described in the “Constants” section of NSAttributedString AppKit Additions Reference ("Option keys for importing documents").

On return, the documentAttributes dictionary (if provided) contains the various keys described in the “Constants” section of NSAttributedString AppKit Additions Reference. If unsuccessful, returns NO , 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.
Declared In
NSAttributedString.h

readFromURL:options:documentAttributes:

Sets the contents of receiver from the file at url.

- (BOOL)readFromURL:(NSURL *)url options:(NSDictionary *)options documentAttributes:(NSDictionary **)documentAttributes
Discussion

Filter services can be used to convert the contents of the URL into a format recognized by Cocoa. options can contain one of the values described in the “Constants” section of NSAttributedString AppKit Additions Reference ("Option keys for importing documents").

On return, the documentAttributes dictionary (if provided) contains the various keys described in the “Constants” section of NSAttributedString AppKit Additions Reference.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSAttributedString.h

readFromURL:options:documentAttributes:error:

Sets the contents of receiver from the file at url.

- (BOOL)readFromURL:(NSURL *)url options:(NSDictionary *)opts documentAttributes:(NSDictionary **)dict error:(NSError **)error
Discussion

Filter services can be used to convert the contents of the URL into a format recognized by Cocoa. opts can contain one of the values described in the “Constants” section of NSAttributedString AppKit Additions Reference ("Option keys for importing documents").

On return, the dict dictionary (if provided) contains the various keys described in the “Constants” section of NSAttributedString AppKit Additions Reference. If unsuccessful, returns NO , after setting error to point to an NSError object that encapsulates the reason why the attributed string object could not be created.

For RTF formatted files, the contents of the file are appended to the previous string instead of replacing the previous string. Therefore, when using this method with existing content it's best to clear the content away explicitly.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
NSAttributedString.h

setAlignment:range:

Sets the alignment characteristic of the paragraph style attribute for the characters in aRange to alignment.

- (void)setAlignment:(NSTextAlignment)alignment range:(NSRange)aRange
Discussion

When attribute fixing takes place, this change will affect only paragraphs whose first character was included in aRange. 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

setBaseWritingDirection:range:

Sets the base writing direction for the characters in range to writingDirection.

- (void)setBaseWritingDirection:(NSWritingDirection)writingDirection range:(NSRange)range
Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
NSAttributedString.h

subscriptRange:

Decrements the value of the superscript attribute for characters in aRange by 1.

- (void)subscriptRange:(NSRange)aRange
Discussion

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

superscriptRange:

Increments the value of the superscript attribute for characters in aRange by 1.

- (void)superscriptRange:(NSRange)aRange
Discussion

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

unscriptRange:

Removes the superscript attribute from the characters in aRange.

- (void)unscriptRange:(NSRange)aRange
Discussion

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

updateAttachmentsFromPath:

Updates all attachments based on files contained in the RTFD file package at path.

- (void)updateAttachmentsFromPath:(NSString *)path
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTextAttachment.h