API 0.9.5
CPAttributedString Class Reference

A mutable character string with attributes. More...

#import <CPAttributedString.h>

Inheritance diagram for CPAttributedString:

List of all members.

Instance Methods

(void) - addAttribute:value:range:
(void) - addAttributes:range:
(void) - appendAttributedString:
(id) - attribute:atIndex:effectiveRange:
(id) - attribute:atIndex:longestEffectiveRange:inRange:
(CPAttributedString- attributedSubstringFromRange:
(CPDictionary- attributesAtIndex:effectiveRange:
(CPDictionary- attributesAtIndex:longestEffectiveRange:inRange:
(void) - beginEditing
(void) - deleteCharactersInRange:
(void) - endEditing
(id) - initWithAttributedString:
(id) - initWithString:
(id) - initWithString:attributes:
(void) - insertAttributedString:atIndex:
(BOOL) - isEqual:
(BOOL) - isEqualToAttributedString:
(unsigned) - length
(CPString- mutableString
(void) - removeAttribute:range:
(void) - replaceCharactersInRange:withAttributedString:
(void) - replaceCharactersInRange:withString:
(void) - setAttributedString:
(void) - setAttributes:range:
(CPString- string

Detailed Description

A mutable character string with attributes.

A character string with sets of attributes that apply to single or ranges of characters. The attributes are contained within a CPDictionary class. Attributes can be any name/value pair. The data type of the value is not restricted. This class is mutable.

Note:
Cocoa developers: in Cappuccino CPAttributedString is mutable. It implements functionality from both NSAttributedString and NSMutableAttributedString. However, to ease converting of existing Objective-C code a CPMutableAttributedString alias to this class exists.

Definition at line 2 of file CPAttributedString.h.


Method Documentation

- (void) addAttribute: (CPString anAttribute
value: (id)  aValue
range: (CPRange)  aRange 

Add an attribute with the given name and value to the specified character range.

Note:
Attributes currently associated with the characters in the range are untouched. To remove all previous attributes when adding use -setAttributes:range:.
Parameters:
anAttributea CPString of the attribute name.
aValuea value to assign to the attribute. Can be of any type.
aRangea CPRange indicating the range of characters to add the attribute too.

Definition at line 615 of file CPAttributedString.j.

- (void) addAttributes: (CPDictionary aDictionary
range: (CPRange)  aRange 

Add a collection of attributes to the specified character range.

Note:
Attributes currently associated with the characters in the range are untouched. To remove all previous attributes when adding use -setAttributes:range:.
Parameters:
aDictionarya CPDictionary of attributes (names and values) to add.
aRangea CPRange indicating the range of characters to add the attributes to.

Definition at line 579 of file CPAttributedString.j.

- (void) appendAttributedString: (CPAttributedString aString

Append an attributed string (characters and attributes) on to the end of the receiver.

Parameters:
aStringa CPAttributedString to append.

Definition at line 648 of file CPAttributedString.j.

- (id) attribute: (CPString attribute
atIndex: (unsigned)  index
effectiveRange: (CPRangePointer)  aRange 

Returns the specified named attribute for the given character index and, if required, the range over which the attribute applies.

Note:
there is no guarantee that the range returned is in fact the complete range of a particular attribute. To ensure this use -attribute:atIndex:longestEffectiveRange:inRange: instead but note that it may take significantly longer to execute.
Parameters:
attributethe name of the desired attribute.
anIndexis an unsigned integer character index from which to retrieve the attribute. It must lie within the bounds of the string.
aRangeis a reference to a CPRange object, that is set upon return to the range over which the named attribute applies. If not required pass nil.
Returns:
the named attribute or nil is the attribute does not exist.

Definition at line 281 of file CPAttributedString.j.

- (id) attribute: (CPString attribute
atIndex: (unsigned)  anIndex
longestEffectiveRange: (CPRangePointer)  aRange
inRange: (CPRange)  rangeLimit 

Returns the specified named attribute for the given character index and the range over which the attribute applies. This is the maximum range both forwards and backwards in the string over which the attribute applies, bounded in both directions by the range limit parameter, rangeLimit.

Note:
this method performs a search to find this range which may be computationally intensive. Use the rangeLimit to limit the search space or use -attribute:atIndex:effectiveRange: but note that it is not guaranteed to return the full range of the current character's named attribute.
Parameters:
attributethe name of the desired attribute.
anIndexis an unsigned integer character index from which to retrieve the attribute. It must lie within the bounds of the string.
aRangeis a reference to a CPRange object, that is set upon return to the range over which the named attribute applies.
rangeLimita range limiting the search for the attribute's applicable range.
Returns:
the named attribute or nil is the attribute does not exist.

Definition at line 318 of file CPAttributedString.j.

- (CPAttributedString) attributedSubstringFromRange: (CPRange)  aRange

Extracts a substring from the receiver, both characters and attributes, within the range given by aRange.

Parameters:
aRangethe range of the substring to extract.
Returns:
a CPAttributedString containing the desired substring.
Exceptions:
CPRangeExceptionif the range lies outside the receiver's bounds.

Definition at line 439 of file CPAttributedString.j.

- (CPDictionary) attributesAtIndex: (unsigned)  anIndex
effectiveRange: (CPRangePointer)  aRange 

Returns a dictionary of attributes for the character at a given index. The range in which this character resides in which the attributes are the same, can be returned if desired.

Note:
there is no guarantee that the range returned is in fact the complete range of the particular attributes. To ensure this use attributesAtIndex:longestEffectiveRange:inRange: instead. Note however that it may take significantly longer to execute.
Parameters:
anIndexis an unsigned integer index. It must lie within the bounds of the string.
aRangeis a reference to a CPRange object that is set (upon return) to the range over which the attributes are the same as those at index, anIndex. If not required pass nil.
Returns:
a CPDictionary containing the attributes associated with the character at index anIndex. Returns nil if index is out of bounds.

Definition at line 166 of file CPAttributedString.j.

- (CPDictionary) attributesAtIndex: (unsigned)  anIndex
longestEffectiveRange: (CPRangePointer)  aRange
inRange: (CPRange)  rangeLimit 

Returns a dictionary of all attributes for the character at a given index and, by reference, the range over which the attributes apply. This is the maximum range both forwards and backwards in the string over which the attributes apply, bounded in both directions by the range limit parameter, rangeLimit.

Note:
this method performs a search to find this range which may be computationally intensive. Use the rangeLimit to limit the search space or use -attributesAtIndex:effectiveRange: but note that it is not guaranteed to return the full range of the current character's attributes.
Parameters:
anIndexis the unsigned integer index. It must lie within the bounds of the string.
aRangeis a reference to a CPRange object that is set (upon return) to the range over which the attributes apply.
rangeLimita range limiting the search for the attributes' applicable range.
Returns:
a CPDictionary containing the attributes associated with the character at index anIndex. Returns nil if index is out of bounds.

Definition at line 205 of file CPAttributedString.j.

- (void) beginEditing

This function is deliberately empty. It is provided to ease code converting from Cocoa.

Definition at line 774 of file CPAttributedString.j.

- (void) deleteCharactersInRange: (CPRange)  aRange

Deletes a range of characters and their associated attributes.

Parameters:
aRangea CPRange indicating the range of characters to delete.

Definition at line 536 of file CPAttributedString.j.

- (void) endEditing

This function is deliberately empty. It is provided to ease code converting from Cocoa.

Definition at line 783 of file CPAttributedString.j.

- (id) initWithAttributedString: (CPAttributedString aString

Creates a new attributed string from an existing attributed string.

Parameters:
aStringis the attributed string to initialise from.
Returns:
a new CPAttributedString containing the string aString.

Definition at line 62 of file CPAttributedString.j.

- (id) initWithString: (CPString aString

Creates a new attributed string from a character string.

Parameters:
aStringis the string to initialise from.
Returns:
a new CPAttributedString containing the string aString.

Definition at line 52 of file CPAttributedString.j.

- (id) initWithString: (CPString aString
attributes: (CPDictionary attributes 

Creates a new attributed string from a character string and the specified dictionary of attributes.

Parameters:
aStringis the attributed string to initialise from.
attributesis a dictionary of string attributes.
Returns:
a new CPAttributedString containing the string aString with associated attributes, attributes.

Definition at line 79 of file CPAttributedString.j.

- (void) insertAttributedString: (CPAttributedString aString
atIndex: (unsigned)  anIndex 

Inserts an attributed string (characters and attributes) at index, anIndex, into the receiver. The portion of the receiver's attributed string from the specified index to the end is shifted until after the inserted string.

Parameters:
aStringa CPAttributedString to insert.
anIndexthe index at which the insert is to occur.
Exceptions:
CPRangeExceptionIf the index is out of bounds.

Definition at line 662 of file CPAttributedString.j.

- (BOOL) isEqual: (id)  anObject

Determine whether the given object is the same as the receiver. If the specified object is an attributed string then an attributed string compare is performed.

Parameters:
anObjectan object to test for equality.
Returns:
a boolean indicating equality.

Definition at line 420 of file CPAttributedString.j.

- (BOOL) isEqualToAttributedString: (CPAttributedString aString

Compares the receiver's characters and attributes to the specified attributed string, aString, and tests for equality.

Parameters:
aStringthe CPAttributedString to compare.
Returns:
a boolean indicating equality.

Definition at line 386 of file CPAttributedString.j.

- (unsigned) length

Get the length of the string.

Returns:
an unsigned integer equivalent to the number of characters in the string.

Definition at line 121 of file CPAttributedString.j.

- (CPString) mutableString

Returns a string containing the receiver's character data without attributes.

Returns:
a string of type CPString.

Definition at line 111 of file CPAttributedString.j.

- (void) removeAttribute: (CPString anAttribute
range: (CPRange)  aRange 

Remove a named attribute from a character range.

Parameters:
anAttributea CPString specifying the name of the attribute.
aRangea CPRange indicating the range of character from which the attribute will be removed.

Definition at line 626 of file CPAttributedString.j.

- (void) replaceCharactersInRange: (CPRange)  aRange
withAttributedString: (CPAttributedString aString 

Replaces characters and attributes in the range aRange with those of the given attributed string, aString.

Parameters:
aRangea CPRange object specifying the range of characters and attributes in the object to replace.
aStringa CPAttributedString containing the data to be used for replacement.

Definition at line 703 of file CPAttributedString.j.

- (void) replaceCharactersInRange: (CPRange)  aRange
withString: (CPString aString 

Replaces the characters in the receiver with those of the specified string over the range, aRange. If the range has a length of 0 then the specified string is inserted at the range location. The new characters inherit the attributes of the first character in the range that they replace or in the case if a 0 range length, the first character before of after the insert (after if the insert is at location 0).

Note:
the replacement string need not be the same length as the range being replaced. The full aString is inserted and thus the receiver's length changes to match this
Parameters:
aRangethe range of characters to replace.
aStringthe string to replace the specified characters in the receiver.

Definition at line 501 of file CPAttributedString.j.

- (void) setAttributedString: (CPAttributedString aString

Sets the objects characters and attributes to those of aString.

Parameters:
aStringis a CPAttributedString from which the contents will be copied.

Definition at line 714 of file CPAttributedString.j.

- (void) setAttributes: (CPDictionary aDictionary
range: (CPRange)  aRange 

Sets the attributes of the specified character range.

Note:
This process removes the attributes already associated with the character range. If you wish to retain the current attributes use -addAttributes:range:.
Parameters:
aDictionarya CPDictionary of attributes (names and values) to set to.
aRangea CPRange indicating the range of characters to set their associated attributes to aDictionary.

Definition at line 553 of file CPAttributedString.j.

- (CPString) string

Returns a string containing the receiver's character data without attributes.

Returns:
a string of type CPString.

Definition at line 101 of file CPAttributedString.j.


The documentation for this class was generated from the following files:
 All Classes Files Functions Variables Defines