ADC Home > Reference Library > Reference > Legacy Documents > Cocoa > Foundation Reference for Java (Legacy) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSMutableAttributedString

Inherits from
Implements
Package
com.apple.cocoa.foundation
Companion guide

Overview

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.

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 method replaces a range of characters with those from a string, leaving all attribute information outside that range intact. The primitive setAttributesInRange 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.

Tasks

Constructors

Retrieving Character Information

Changing Characters

Changing Attributes

Changing Characters and Attributes

Grouping Changes

Constructors

NSMutableAttributedString

Creates an empty NSMutableAttributedString.

public NSMutableAttributedString()

Creates an NSMutableAttributedString with the characters and attributes of attributedString.

public NSMutableAttributedString(NSAttributedString attributedString)

Creates an NSMutableAttributedString with the contents of aData, returning document properties in attributes.

public NSMutableAttributedString(NSData aData, NSMutableDictionary attributes)

Creates an NSMutableAttributedString from the HTML contained in data and base URL aURL.

public NSMutableAttributedString(NSData data, java.net.url aURL, NSMutableDictionary attributes)

Discussion

Also returns in attributes a dictionary containing document-level attributes described in NSAttributedString’s “Constants.” Returns null if the file at aURL can’t be decoded.

Creates an NSMutableAttributedString from wrapper, an NSFileWrapper object containing an RTFD document.

public NSMutableAttributedString(NSFileWrapper wrapper, NSMutableDictionary attributes)

Discussion

Also returns in attributes a dictionary containing document-level attributes described in NSAttributedString’s “Constants.” Returns null if wrapper can’t be interpreted as an RTFD document.

Creates an NSMutableAttributedString with the characters of string

public NSMutableAttributedString(String string)

Discussion

and no attribute information

Creates an NSMutableAttributedString with the characters of aString and the attributes of attributes.

public NSMutableAttributedString(String aString, NSDictionary attributes)

Creates an NSMutableAttributedString with the contents of aURL, returning document properties, which are described in NSAttributedString’s “Constants,” in attributes.

public NSMutableAttributedString(java.net.URL aURL, NSMutableDictionary attributes)

Creates an NSMutableAttributedString with the contents of aURL, returning document properties, which are described in NSAttributedString’s “Constants,” in attributes.

public NSMutableAttributedString(NSData aURL, NSDictionary options, NSMutableDictionary attributes)

Discussion

options can contain one of the values described in readFromURL.

Instance Methods

addAttributeInRange

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

public void addAttributeInRange(String name, Object value, NSRange aRange)

Discussion

Throws an InvalidArgumentException if name or value is null and a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

addAttributesInRange

Adds the collection of attributes in attributes to the characters in aRange.

public void addAttributesInRange(NSDictionary attributes, NSRange aRange)

Discussion

Throws an InvalidArgumentException if attributes is null and a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

appendAttributedString

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

public void appendAttributedString(NSAttributedString attributedString)

See Also

applyFontTraitsInRange

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

public void applyFontTraitsInRange(int mask, NSRange aRange)

Discussion

See the NSFontManager class specification for a description of the font traits available. Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

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.

public void beginEditing()

Discussion

You can nest pairs of beginEditing and endEditing messages.

deleteCharactersInRange

Deletes the characters in aRange along with their associated attributes.

public void deleteCharactersInRange(NSRange aRange)

Discussion

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

endEditing

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

public void endEditing()

Discussion

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

fixAttachmentAttributeInRange

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

public void fixAttachmentAttributeInRange(NSRange aRange)

Discussion

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

fixAttributesInRange

Invokes the other fix... methods, allowing you to clean up an attributed string with a single message.

public void fixAttributesInRange(NSRange aRange)

Discussion

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

fixFontAttributeInRange

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

public void fixFontAttributeInRange(NSRange aRange)

Discussion

For example, Kanji characters assigned a Latin font are reassigned an appropriate Kanji font. Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

fixParagraphStyleAttributeInRange

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

public void fixParagraphStyleAttributeInRange(NSRange aRange)

Discussion

This method extends the range as needed to cover the last paragraph partially contained. A paragraph is delimited by any of these characters, the longest possible sequence being preferred to any shorter:

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

insertAttributedStringAtIndex

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.

public void insertAttributedStringAtIndex(NSAttributedString attributedString, int index)

Discussion

Throws a RangeException if index lies beyond the end of the receiver’s characters.

See Also

mutableStringReference

Returns the character contents of the receiver as an NSMutableStringReference object.

public NSMutableStringReference mutableStringReference()

Discussion

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

readFromData

public boolean readFromData(NSData data, NSDictionary options, NSMutableDictionary dict)

Discussion

Sets the contents of the receiver from the stream at data. options can contain one of the values described in readFromURL.

On return, the documentAttributes dictionary (if provided) contains the various keys described in the “Constants” section of NSAttributedString.

Availability

readFromURL

Sets the contents of receiver from the file at url.

public boolean readFromURL(java.net.URL url, NSDictionary options, NSMutableDictionary documentAttributes)

Discussion

Filter services can be used to convert the contents of the URL into a format recognized by Cocoa. options can contain:

Key

Description

CharacterEncoding

For plain text documents; the unsigned int to be used if the encoding cannot be determined

BaseURL

For HTML documents; java.net.URL containing base URL

DefaultAttributes

NSDictionary containing attributes to be applied to plain files

Starting with Mac OS X v10.3, these options keys are recognized for HTML documents, both by this method as well as the NSAttributedString constructor with an options parameter:

Key

Description

"UseWebKit"

An integer. If present and positive, forces WebKit-based HTML importing be used; behavior in this case may differ from HTML import in Mac OS X v10.2 and before, particularly for tables.

"TextEncodingName"

String containing the name, IANA or otherwise, of a text encoding to be used if the encoding cannot be determined from the document. Mutually exclusive with "CharacterEncoding".

"Timeout"

A float. Time in seconds to wait for a document to finish loading.

"WebPreferences"

WebPreferences. If WebKit-based HTML importing is used, specifies a WebPreferences object. If not present, a default set of preferences is used.

"WebResourceLoadDelegate"

NSObject. If WebKit-based HTML importing is used, specifies an object to serve as the WebResourceLoadDelegate. If not present, a default delegate will be used that will permit the loading of subsidiary resources but will not respond to authentication challenges.

On return, the documentAttributes dictionary (if provided) contains the various keys described in the “Constants” section of NSAttributedString.

removeAttributeInRange

Removes the attribute named name from the characters in aRange.

public void removeAttributeInRange(String name, NSRange aRange)

Discussion

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

replaceCharactersInRange

Replaces the characters and attributes in aRange with the characters and attributes of attributedString.

public void replaceCharactersInRange(NSRange aRange, NSAttributedString attributedString)

Discussion

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

Replaces the characters in aRange with the characters of aString.

public void replaceCharactersInRange(NSRange aRange, String aString)

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.

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

setAlignmentInRange

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

public void setAlignmentInRange(int alignment, NSRange aRange)

Discussion

When attribute fixing takes place, this change will affect only paragraphs whose first character was included in aRange. Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

setAttributedString

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

public void setAttributedString(NSAttributedString attributedString)

See Also

setAttributesInRange

Sets the attributes for the characters in aRange to attributes.

public void setAttributesInRange(NSDictionary attributes, NSRange aRange)

Discussion

These new attributes replace any attributes previously associated with the characters in aRange. Throws a RangeException 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.

See Also

subscriptRange

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

public void subscriptRange(NSRange aRange)

Discussion

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

superscriptRange

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

public void superscriptRange(NSRange aRange)

Discussion

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

unscriptRange

Removes the superscript attribute from the characters in aRange.

public void unscriptRange(NSRange aRange)

Discussion

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

updateAttachmentsFromPath

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

public void updateAttachmentsFromPath(String path)

See Also


Next Page > Hide TOC

© 1997, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-24)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.