Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/Foundation.framework |
Availability | Available in Mac OS X v10.0 and later. |
Companion guide | |
Declared in | NSAttributedString.h |
Related sample code |
NSMutableAttributedString
declares the programmatic interface to objects that manage mutable attributed strings. You can add and remove characters (raw strings) and attributes separately or together as attributed strings. See the class description for NSAttributedString for more information about attributed strings.
When working with the Application Kit, you must also clean up changed attributes using the various fix...
methods. See “Changing an Attributed String“ for more information on fixing attributes. These methods, as well as others involving setting graphical attributes, are described in NSMutableAttributedString Additions in the Application Kit.
NSMutableAttributedString
adds two primitive methods to those of NSAttributedString
. These primitive methods provide the basis for all the other methods in its class. The primitive replaceCharactersInRange:withString:
method replaces a range of characters with those from a string, leaving all attribute information outside that range intact. The primitive setAttributes:range:
method sets attributes and values for a given range of characters, replacing any previous attributes and values for that range.
The Application Kit also uses NSParagraphStyle and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString
classes.
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 using, for example, initWithString:attributes:
.
– appendAttributedString:
– insertAttributedString:atIndex:
– replaceCharactersInRange:withAttributedString:
– setAttributedString:
Adds an attribute with the given name and value to the characters in the specified range.
- (void)addAttribute:(NSString *)name value:(id)value range:(NSRange)aRange
A string specifying the attribute name.
The attribute value associated with name.
The range of characters to which the specified attribute/value pair applies.
You may assign any name/value pair you wish to a range of characters, in addition to the standard attributes described in the “Constants” section of NSAttributedString Additions. Raises an NSInvalidArgumentException
if name or value is nil
and an NSRangeException
if any part of aRange lies beyond the end of the receiver’s characters.
NSAttributedString.h
Adds the given collection of attributes to the characters in the specified range.
- (void)addAttributes:(NSDictionary *)attributes range:(NSRange)aRange
A dictionary containing the attributes to add.
The range of characters to which the specified attributes apply.
You may assign any name/value pair you wish to a range of characters, in addition to the standard attributes described in the “Constants” section of NSAttributedString Additions. Raises an NSInvalidArgumentException
if attributes is nil
and an NSRangeException
if any part of aRange lies beyond the end of the receiver’s characters.
NSAttributedString.h
Adds the characters and attributes of a given attributed string to the end of the receiver.
- (void)appendAttributedString:(NSAttributedString *)attributedString
The string whose characters and attributes are added.
– insertAttributedString:atIndex:
+ attributedStringWithAttachment:
(NSAttributedString Additions)NSAttributedString.h
Overridden by subclasses to buffer or optimize a series of changes to the receiver’s characters or attributes, until it receives a matching endEditing
message, upon which it can consolidate changes and notify any observers that it has changed.
- (void)beginEditing
You can nest pairs of beginEditing
and endEditing
messages.
NSAttributedString.h
Deletes the characters in the given range along with their associated attributes.
- (void)deleteCharactersInRange:(NSRange)aRange
A range specifying the characters to delete.
Raises an NSRangeException
if any part of aRange lies beyond the end of the receiver’s characters.
NSAttributedString.h
Overridden by subclasses to consolidate changes made since a previous beginEditing
message and to notify any observers of the changes.
- (void)endEditing
The NSMutableAttributedString
implementation does nothing. NSTextStorage
, for example, overrides this method to invoke fixAttributesInRange:
and to inform its NSLayoutManager
objects that they need to re-lay the text.
– processEditing
(NSTextStorage
)NSAttributedString.h
Inserts the characters and attributes of the given attributed string into the receiver at the given index.
- (void)insertAttributedString:(NSAttributedString *)attributedString atIndex:(NSUInteger)index
The string whose characters and attributes are inserted.
The index at which the characters and attributes are inserted.
The new characters and attributes begin at the given index and the existing characters and attributes from the index to the end of the receiver are shifted by the length of the attributed string. Raises an NSRangeException
if index lies beyond the end of the receiver’s characters.
– appendAttributedString:
+ attributedStringWithAttachment:
(NSAttributedString Additions)NSAttributedString.h
Returns the character contents of the receiver as an NSMutableString
object.
- (NSMutableString *)mutableString
The mutable string object.
The receiver tracks changes to this string and keeps its attribute mappings up to date.
NSAttributedString.h
Removes the named attribute from the characters in the specified range.
- (void)removeAttribute:(NSString *)name range:(NSRange)aRange
A string specifying the attribute name to remove.
The range of characters from which the specified attribute is removed.
Raises an NSRangeException
if any part of aRange lies beyond the end of the receiver’s characters.
NSAttributedString.h
Replaces the characters and attributes in a given range with the characters and attributes of the given attributed string.
- (void)replaceCharactersInRange:(NSRange)aRange withAttributedString:(NSAttributedString *)attributedString
The range of characters and attributes replaced.
The attributed string whose characters and attributes replace those in the specified range.
Raises an NSRangeException
if any part of aRange lies beyond the end of the receiver’s characters.
NSAttributedString.h
Replaces the characters in the given range with the characters of the given string.
- (void)replaceCharactersInRange:(NSRange)aRange withString:(NSString *)aString
A range specifying the characters to replace.
A string specifying the characters to replace those in aRange
.
The new characters inherit the attributes of the first replaced character from aRange. Where the length of aRange is 0, the new characters inherit the attributes of the character preceding aRange if it has any, otherwise of the character following aRange.
Raises an NSRangeException
if any part of aRange lies beyond the end of the receiver’s characters.
NSAttributedString.h
Replaces the receiver’s entire contents with the characters and attributes of the given attributed string.
- (void)setAttributedString:(NSAttributedString *)attributedString
The attributed string whose characters and attributes replace those in the receiver.
NSAttributedString.h
Sets the attributes for the characters in the specified range to the specified attributes.
- (void)setAttributes:(NSDictionary *)attributes range:(NSRange)aRange
A dictionary containing the attributes to set.
The range of characters whose attributes are set.
These new attributes replace any attributes previously associated with the characters in aRange. Raises an NSRangeException
if any part of aRange lies beyond the end of the receiver’s characters.
To set attributes for a zero-length NSMutableAttributedString
displayed in a text view, use the NSTextView
method setTypingAttributes:
.
NSAttributedString.h
An attributed string identifies attributes by name, storing a value under the name in an NSDictionary
object. You can assign any attribute name/value pair you wish to a range of characters, in addition to the standard attributes described in the “Constants” section of NSAttributedString Additions.
© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-06-28)