iOS Developer Library

Developer

Foundation Framework Reference NSMutableAttributedString Class Reference

Options
Deployment Target:

On This Page
Language:

NSMutableAttributedString

The NSMutableAttributedString class declares additional methods for mutating the content of an attributed string. 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.

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, AppKit 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 may differ from the OS X system font, 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.

    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.

    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.

    Availability

    Available in iOS 3.2 and later.

    See Also

    – processEditing (NSTextStorage)

  • Cleans up font, paragraph style, and attachment attributes within the given range.

    Declaration

    Swift

    func fixAttributesInRange(_ range: NSRange)

    Objective-C

    - (void)fixAttributesInRange:(NSRange)range

    Parameters

    range

    The character range within which to fix attributes. Raises an NSRangeException if any part of range lies beyond the end of the receiver’s characters.

    Discussion

    Removes attachment attributes assigned to characters other than NSAttachmentCharacter, assigns default fonts to characters with illegal fonts for their scripts and otherwise corrects font attribute assignments, and assigns the first paragraph style attribute value in each paragraph to all characters of the paragraph.

    This method extends the range as needed to cover the last paragraph partially contained.

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

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.