iOS Developer Library

Developer

Foundation Framework Reference NSMutableAttributedString Class Reference

Options
Deployment Target:

On This Page
Language:

NSMutableAttributedString

Inheritance


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 3.2 and later.

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.

In OS X, 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 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:.

NSMutableAttributedString is “toll-free bridged” with its Core Foundation counterpart, CFMutableAttributedStringRef. See Toll-Free Bridging for more information.

  • The character contents of the receiver as an NSMutableString object.

    Declaration

    Swift

    var mutableString: NSMutableString { get }

    Objective-C

    @property(readonly, retain) NSMutableString *mutableString

    Return Value

    The mutable string object.

    Discussion

    The receiver tracks changes to this string and keeps its attribute mappings up to date.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • Replaces the characters in the given range with the characters of the given string.

    Declaration

    Swift

    func replaceCharactersInRange(_ aRange: NSRange, withString aString: String)

    Objective-C

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

    Parameters

    aRange

    A range specifying the characters to replace.

    aString

    A string specifying the characters to replace those in aRange.

    Discussion

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • Deletes the characters in the given range along with their associated attributes.

    Declaration

    Swift

    func deleteCharactersInRange(_ aRange: NSRange)

    Objective-C

    - (void)deleteCharactersInRange:(NSRange)aRange

    Parameters

    aRange

    A range specifying the characters to delete.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • Sets the attributes for the characters in the specified range to the specified attributes.

    Declaration

    Swift

    func setAttributes(_ attributes: [NSObject : AnyObject]?, range aRange: NSRange)

    Objective-C

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

    Parameters

    attributes

    A dictionary containing the attributes to set. Attribute keys can be supplied by another framework or can be custom ones you define. For information about where to find the system-supplied attribute keys, see the overview section in NSAttributedString Class Reference.

    aRange

    The range of characters whose attributes are set.

    Discussion

    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:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • Adds an attribute with the given name and value to the characters in the specified range.

    Declaration

    Swift

    func addAttribute(_ name: String, value value: AnyObject, range aRange: NSRange)

    Objective-C

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

    Parameters

    name

    A string specifying the attribute name. Attribute keys can be supplied by another framework or can be custom ones you define. For information about where to find the system-supplied attribute keys, see the overview section in NSAttributedString Class Reference.

    value

    The attribute value associated with name.

    aRange

    The range of characters to which the specified attribute/value pair applies.

    Discussion

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • Adds the given collection of attributes to the characters in the specified range.

    Declaration

    Swift

    func addAttributes(_ attributes: [NSObject : AnyObject], range aRange: NSRange)

    Objective-C

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

    Parameters

    attributes

    A dictionary containing the attributes to add. Attribute keys can be supplied by another framework or can be custom ones you define. For information about where to find the system-supplied attribute keys, see the overview section in NSAttributedString Class Reference.

    aRange

    The range of characters to which the specified attributes apply.

    Discussion

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • Removes the named attribute from the characters in the specified range.

    Declaration

    Swift

    func removeAttribute(_ name: String, range aRange: NSRange)

    Objective-C

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

    Parameters

    name

    A string specifying the attribute name to remove. Attribute keys can be supplied by another framework or can be custom ones you define. For information about where to find the system-supplied attribute keys, see the overview section in NSAttributedString Class Reference.

    aRange

    The range of characters from which the specified attribute is removed.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • Adds the characters and attributes of a given attributed string to the end of the receiver.

    Declaration

    Swift

    func appendAttributedString(_ attributedString: NSAttributedString)

    Objective-C

    - (void)appendAttributedString:(NSAttributedString *)attributedString

    Parameters

    attributedString

    The string whose characters and attributes are added.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • Inserts the characters and attributes of the given attributed string into the receiver at the given index.

    Declaration

    Swift

    func insertAttributedString(_ attributedString: NSAttributedString, atIndex index: Int)

    Objective-C

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

    Parameters

    attributedString

    The string whose characters and attributes are inserted.

    index

    The index at which the characters and attributes are inserted.

    Discussion

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

    See Also

    – appendAttributedString:
    + attributedStringWithAttachment: (NSAttributedString Additions)

  • Replaces the characters and attributes in a given range with the characters and attributes of the given attributed string.

    Declaration

    Swift

    func replaceCharactersInRange(_ aRange: NSRange, withAttributedString attributedString: NSAttributedString)

    Objective-C

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

    Parameters

    aRange

    The range of characters and attributes replaced.

    attributedString

    The attributed string whose characters and attributes replace those in the specified range.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • Replaces the receiver’s entire contents with the characters and attributes of the given attributed string.

    Declaration

    Swift

    func setAttributedString(_ attributedString: NSAttributedString)

    Objective-C

    - (void)setAttributedString:(NSAttributedString *)attributedString

    Parameters

    attributedString

    The attributed string whose characters and attributes replace those in the receiver.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • 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.

    Declaration

    Swift

    func beginEditing()

    Objective-C

    - (void)beginEditing

    Discussion

    You can nest pairs of beginEditing and endEditing messages.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

  • Overridden by subclasses to consolidate changes made since a previous beginEditing message and to notify any observers of the changes.

    Declaration

    Swift

    func endEditing()

    Objective-C

    - (void)endEditing

    Discussion

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.2 and later.

    See Also

    – processEditing (NSTextStorage)