PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSAttributedString


Inherits from:
NSObject
Package:
com.apple.yellow.foundation


Class Description


NSAttributedString objects manage character strings and associated sets of attributes (for example, font and kerning) that apply to individual characters or ranges of characters in the string. An association of characters and their attributes is called an attributed string. The cluster's two public classes, NSAttributedString and NSMutableAttributedString, declare the programmatic interface for read-only attributed strings and modifiable attributed strings, respectively. The Application Kit uses a subclass of NSMutableAttributedString, called NSTextStorage, to provide the storage for the Application Kit's extended text-handling system.

NSAttributedString is not a subclass of String. It contains a string object to which it applies attributes. This protects users of attributed strings from ambiguities caused by the semantic differences between simple and attributed string. For example, equality can't be simply defined between a String and an attributed string.

You create an NSAttributedString object by using one of the Constructors. These methods initialize an attributed string with data you provide. The Application Kit also provides methods for creating attributed strings from RTF data.

An attributed string provides basic access to its contents with the stringReference and attributesAtIndex methods, which yield characters and attributes, respectively. These two primitive methods are used by the other access methods to retrieve attributes individually by name, by functional group (font or ruler attributes, for example), and so on.

The attribute values assigned to an attributed string become the property of that string, and shouldn't be modified in any way by other objects. Doing so can render inconsistent the attributed string's internal state. Always use NSMutableAttributedString's setAttributesInRange and related methods to change attribute values.

The NSAttributedString class declares the programmatic interface to an object that manages an immutable attributed string. NSAttributedString's two primitive methods provide the basis for all the other methods in the class. The primitive stringReference method returns the NSStringReference object to which attributes are applied. The primitive attributesAtIndex method returns an NSDictionary containing the attribute names and values for characters around a specified index.




Constants


NSAttributedString provides the following constants as a convenience:


Constant Type Description
AttachmentAttributeName String NSAttachment
BackgroundColorAttributeName String NSBackgroundColor
BaselineOffsetAttributeName String NSBaselineOffset
FontAttributeName String NSFont
ForegroundColorAttributeName String NSColor
KernAttributeName String NSKern
LigatureAttributeName String NSLigature
LinkAttributeName String NSLink
NoUnderlineStyle int 0
ParagraphStyleAttributeName String NSParagraphStyle
SingleUnderlineStyle int 1
SuperscriptAttributeName String NSSuperScript
UnderlineByWordMask int 32768
UnderlineStrikethroughMask int 16384
UnderlineStyleAttributeName String NSUnderline



Method Types


Constructors
NSAttributedString
Retrieving character information
stringReference
length
Retrieving attribute information
attributesAtIndex
attributeAtIndex
Comparing attributed strings
isEqualToAttributedString
Extracting a substring
attributedSubstringWithRange


Constructors



NSAttributedString

public NSAttributedString()

Description forthcoming.

public NSAttributedString(String aString)

Initializes a newly allocated NSAttributedString object with the characters of aString and no attribute information. Returns this.

public NSAttributedString( String aString, NSDictionary aNSDictionary)

Initializes a newly allocated NSAttributedString object with the characters of aString and the attributes of attributes. Returns this.

public NSAttributedString(NSAttributedString aNSAttributedString)

Initializes a newly allocated NSAttributedString object with the characters and attributes of attributedString. Returns this.

public NSAttributedString( URL anURL, NSMutableDictionary aNSMutableDictionary)

Description forthcoming.

public NSAttributedString( NSData aNSData, NSMutableDictionary aNSMutableDictionary)

Description forthcoming.

public NSAttributedString( Object anObject, NSMutableDictionary aNSMutableDictionary)

Description forthcoming.

public NSAttributedString( NSData aNSData, Object anObject, NSMutableDictionary aNSMutableDictionary)

Description forthcoming.


Instance Methods



RTFDFileWrapperFromRange

public Object RTFDFileWrapperFromRange( NSRange aNSRange, NSDictionary aNSDictionary)

Description forthcoming.

RTFFromRange

public NSData RTFFromRange( NSRange aNSRange, NSDictionary aNSDictionary)

Description forthcoming.

attributeAtIndex

public Object attributeAtIndex( String attributeName, int index, NSMutableRange aRange)

Returns the value for the attribute named attributeName of the character at index, or null if there is no such attribute. If the named attribute exists at index and aRange is non-null, it's filled with a range over which the named attribute's value applies. If the named attribute doesn't exist at index and aRange is non-null, aRange is filled instead with the range over which the attribute doesn't exist. This range isn't necessarily the maximum range covered by attributeName, and its extent is implementation-dependent.

Throws an exception if index lies beyond the end of the receiver's characters.

public Object attributeAtIndex( String attributeName, int index, NSMutableRange aRange, NSRange rangeLimit)

Returns the value for the attribute named attributeName of the character at index, or null if there is no such attribute. If the named attribute exists at index and aRange is non-null, it's filled with the full range over which the value of the named attribute is the same as that at index, clipped to rangeLimit. If the named attribute doesn't exist at index and aRange is non-null, aRange is filled instead with the full range over which the attribute doesn't exist, clipped to rangeLimit.

Throws an exception if index or any part of rangeLimit lies beyond the end of the receiver's characters.

See Also: attributesAtIndex



attributedSubstringWithRange

public NSAttributedString attributedSubstringWithRange(NSRange aRange)

Returns an NSAttributedString object consisting of the characters and attributes within aRange in the receiver. Throws a RangeException if any part of aRange lies beyond the end of the receiver's characters.

attributesAtIndex

public NSDictionary attributesAtIndex( int index, NSMutableRange aRange)

Returns the attributes for the character at index. If aRange is non-null it's filled with the range over which the attributes and values apply. This range isn't necessarily the maximum range covered, and its extent is implementation-dependent.

Throws an exception if index lies beyond the end of the receiver's characters.

public NSDictionary attributesAtIndex( int index, NSMutableRange aRange, NSRange rangeLimit)

Returns the attributes for the character at index. If aRange is non-null, it's filled with the maximum range over which the attributes and values are the same as those at index, clipped to rangeLimit.

Throws an exception if index or any part of rangeLimit lies beyond the end of the receiver's characters.

See Also: attributeAtIndex



containsAttachments

public boolean containsAttachments()

Description forthcoming.

doubleClickAtIndex

public NSRange doubleClickAtIndex(int anInt)

Description forthcoming.

fontAttributesInRange

public NSDictionary fontAttributesInRange(NSRange aNSRange)

Description forthcoming.

isEqualToAttributedString

public boolean isEqualToAttributedString(NSAttributedString otherString)

Returns true if the receiver is equal to otherString. Attributed strings must match in both characters and attributes to be equal.

length

public int length()

Returns the length of the receiver's string object.

See Also: length (NSStringReference)



lineBreakBeforeIndex

public int lineBreakBeforeIndex( int anInt, NSRange aNSRange)

Description forthcoming.

nextWordFromIndex

public int nextWordFromIndex( int anInt, boolean aBoolean)

Description forthcoming.

rulerAttributesInRange

public NSDictionary rulerAttributesInRange(NSRange aNSRange)

Description forthcoming.

stringReference

public NSStringReference stringReference()

Returns the character contents of the receiver as an NSStringReference object. This method doesn't strip out attachment characters; use NSText's string method to extract just the linguistically significant characters.

This primitive method must guarantee efficient access to an attributed string's characters; subclasses should implement it to execute in O(1) time.




Table of Contents