PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSMutableAttributedString


Inherits from:
NSAttributedString : NSObject
Conforms to:
NSCoding
(NSAttributedString)
NSCopying (NSAttributedString)
NSMutableCopying (NSAttributedString)
NSObject (NSObject)
Declared in:
Foundation/NSAttributedString.h




Class Description


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 NSAttributedString's class description 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 the Application Kit's specification for this class cluster for more information on fixing attributes.

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.




Method Types


Retrieving character information
- mutableString
Changing characters
- replaceCharactersInRange:withString:
- deleteCharactersInRange:
Changing attributes
- setAttributes:range:
- addAttribute:value:range:
- addAttributes:range:
- removeAttribute:range:
Changing characters and attributes
- appendAttributedString:
- insertAttributedString:atIndex:
- replaceCharactersInRange:withAttributedString:
- setAttributedString:
Grouping changes
- beginEditing
- endEditing


Instance Methods



addAttribute:value:range:

- (void)addAttribute:(NSString *)name value:(id)value range:(NSRange)aRange

Adds an attribute with the given name and value to the characters in aRange. 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.

See Also: - addAttributes:range:, - removeAttribute:range:



addAttributes:range:

- (void)addAttributes:(NSDictionary *)attributes range:(NSRange)aRange

Adds the collection of attributes in attributes to the characters in aRange. Raises an NSInvalidArgumentException if attributes is nil and an NSRangeException if any part of aRange lies beyond the end of the receiver's characters.

See Also: - addAttribute:value:range:, - removeAttribute:range:



appendAttributedString:

- (void)appendAttributedString:(NSAttributedString *)attributedString

Adds the characters and attributes of attributedString to the end of the receiver.

See Also: - insertAttributedString:atIndex:, + attributedStringWithAttachment: (NSAttributedString Additions in the Application Kit)



beginEditing

- (void)beginEditing

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. You can nest pairs of beginEditing and endEditing messages.

deleteCharactersInRange:

- (void)deleteCharactersInRange:(NSRange)aRange

Deletes the characters in aRange along with their associated attributes. Raises an NSRangeException if any part of aRange lies beyond the end of the receiver's characters.

See Also: - replaceCharactersInRange:withAttributedString:, - replaceCharactersInRange:withString:



endEditing

- (void)endEditing

Overridden by subclasses to consolidate changes made since a previous beginEditing message and to notify any observers of the changes. NSMutableAttributedString's implementation does nothing. NSTextStorage, for example, overrides this method to invoke fixAttributesInRange: and to inform its NSLayoutManagers that they need to re-lay the text.

See Also: - processEditing (NSTextStorage class in the Application Kit)



insertAttributedString:atIndex:

- (void)insertAttributedString:(NSAttributedString *)attributedString atIndex:(unsigned)index

Inserts the characters and attributes of attributedString into the receiver, so the new characters and attributes begin at index and the existing characters and attributes from index to the end are shifted by the length of attributedString. Raises an NSRangeException if index lies beyond the end of the receiver's characters.

See Also: - appendAttributedString:, + attributedStringWithAttachment: (NSAttributedString Additions in the Application Kit)



mutableString

- (NSMutableString *)mutableString

Returns the character contents of the receiver as an NSMutableString object. The receiver tracks changes to this string and keeps its attribute mappings up to date.

removeAttribute:range:

- (void)removeAttribute:(NSString *)name range:(NSRange)aRange

Removes the attribute named name from the characters in aRange. Raises an NSRangeException if any part of aRange lies beyond the end of the receiver's characters.

See Also: - addAttribute:value:range:, - addAttributes:range:



replaceCharactersInRange:withAttributedString:

- (void)replaceCharactersInRange:(NSRange)aRange withAttributedString:(NSAttributedString *)attributedString

Replaces the characters and attributes in aRange with the characters and attributes of attributedString. Raises an NSRangeException if any part of aRange lies beyond the end of the receiver's characters.

See Also: - insertAttributedString:atIndex:



replaceCharactersInRange:withString:

- (void)replaceCharactersInRange:(NSRange)aRange withString:(NSString *)aString

Replaces the characters in aRange with the characters of aString. The new characters inherit the attributes of the first replaced character from aRange. Where the length of aRange is zero, 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.

See Also: - deleteCharactersInRange:



setAttributedString:

- (void)setAttributedString:(NSAttributedString *)attributedString

Replaces the receiver's entire contents with the characters and attributes of attributedString.

See Also: - appendAttributedString:



setAttributes:range:

- (void)setAttributes:(NSDictionary *)attributes range:(NSRange)aRange

Sets the attributes for the characters in aRange to attributes. 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.

See Also: - addAttributes:range:, - removeAttribute:range:




Table of Contents