Class

NSMutableAttributedString

A mutable string object that also contains attributes (such as visual style, hyperlinks, or accessibility data) associated with various portions of its text content.

Declaration

@interface NSMutableAttributedString : NSAttributedString

Overview

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 macOS, 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 macOS 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.

Topics

Retrieving character information

mutableString

The character contents of the receiver as an NSMutableString object.

Changing characters

- replaceCharactersInRange:withString:

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

- deleteCharactersInRange:

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

Changing attributes

- setAttributes:range:

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

- addAttribute:value:range:

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

- addAttributes:range:

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

- removeAttribute:range:

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

- applyFontTraits:range:

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

- setAlignment:range:

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

- setBaseWritingDirection:range:

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

- subscriptRange:

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

- superscriptRange:

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

- unscriptRange:

Removes the superscript attribute from the characters in aRange.

Changing characters and attributes

- appendAttributedString:

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

- insertAttributedString:atIndex:

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

- replaceCharactersInRange:withAttributedString:

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

- setAttributedString:

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

Grouping changes

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

- endEditing

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

Updating attachment contents

- updateAttachmentsFromPath:

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

Fixing attributes after changes

- fixAttributesInRange:

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

- fixAttachmentAttributeInRange:

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

- fixFontAttributeInRange:

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

- fixParagraphStyleAttributeInRange:

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