Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSTextStorage


Inherits from:
NSMutableAttributedString : NSAttributedString : NSObject
Package:
com.apple.yellow.application


Class Description


NSTextStorage is a semi-concrete subclass of NSMutableAttributedString that manages a set of client NSLayoutManagers, notifying them of any changes to its characters or attributes so that they can re-lay and redisplay the text as needed. NSTextStorage defines the fundamental storage mechanism of the Application Kit's extended text-handling system.

To create an NSTextStorage, use one if its constructors. Following this, you add NSLayoutManagers to it using addLayoutManager.

The behavior of an NSTextStorage object is best illustrated by following the methods it invokes while being changed. There are three stages to editing a text storage object programmatically. The first stage is to send it a beginEditing message to announce a group of changes. In the second stage, you send it some editing messages, such as deleteCharactersInRange: and addAttributes:range:, to effect the changes in characters or attributes. Each time you send such a method, the text storage object invokes editedInRange to record the range of its characters affected since it received the beginEditing message. For the third stage, when you're done changing the text storage object, you send it an appropriate message. This causes it to invoke its own processEditing method, fixing attributes within the recorded range of changed characters. After fixing its attributes, the text storage object sends a message to each NSLayoutManager indicating the range in the text storage object that has changed, along with the nature of those changes. The NSLayoutManagers in turn use this information to re-lay their glyphs and redisplay if necessary. NSTextStorage also keeps a delegate and sends it messages before and after processing edits.


Creating a Subclass of NSTextStorage


As indicated above, NSTextStorage isn't a fully concrete class. It defines the storage for its NSLayoutManagers and implements all of the methods described in this specification, but doesn't provide the primitive attributed string methods to subclasses. A subclass must define the storage for its attributed string, typically as an instance variable of type NSMutableAttributedString, define constructors, and implement the primitive methods of both NSAttributedString and NSMutableAttributedString. For the record, these methods are:

Beyond these requirements, if a subclass overrides or adds any methods that change its characters or attributes directly (not using the primitive methods or making extra changes after invoking the primitives), those methods must invoke editedInRange after performing the change in order to keep the change-tracking information up to date. See the description of this method for more information.




Method Types


Constructors
NSTextStorage
Managing NSLayoutManagers
addLayoutManager
removeLayoutManager
layoutManagers
Handling text edited messages
editedInRange
ensureAttributesAreFixedInRange
fixesAttributesLazily
invalidateAttributesInRange
processEditing
replaceCharactersInRange
setAttributesInRange
Determining the nature of changes
editedMask
Determining the extent of changes
editedRange
changeInLength
Setting the delegate
setDelegate
delegate


Constructors



NSTextStorage

public NSTextStorage()

Description forthcoming.

public NSTextStorage(String aString)

Description forthcoming.

public NSTextStorage( String aString, NSDictionary aDictionary)

Description forthcoming.

public NSTextStorage(NSAttributedString anAttributedString)

Description forthcoming.

public NSTextStorage( java.net.URL anURL, NSMutableDictionary aDictionary)

Description forthcoming.

public NSTextStorage( NSData data, NSMutableDictionary aDictionary)

Description forthcoming.

public NSTextStorage( Object anObject, NSMutableDictionary aDictionary)

Description forthcoming.

public NSTextStorage( NSData data, Object anObject, NSMutableDictionary aDictionary)

Description forthcoming.

public NSTextStorage( String aString, NSMutableDictionary aDictionary)

Description forthcoming.


Instance Methods



addLayoutManager

public void addLayoutManager(NSLayoutManager aLayoutManager)

Adds aLayoutManager to the receiver's set of NSLayoutManagers.

See Also: removeLayoutManager, layoutManagers



changeInLength

public int changeInLength()

Returns the difference between the current length of the edited range and its length before editing began (that is, before the receiver was sent the first beginEditing message or a single editedInRange message). This difference is accumulated with each invocation of editedInRange, until a final message processes the changes.

The receiver's delegate and layout managers can use this information to determine the nature of edits in their respective notification methods.

See Also: editedRange, editedMask



delegate

public Object delegate()

Returns the receiver's delegate.

See Also: setDelegate



editedInRange

public void editedInRange( int mask, NSRange oldRange, int lengthChange)

Tracks changes made to the receiver, allowing the NSTextStorage to record the full extent of changes made. This method invokes processEditing. NSTextStorage invokes this method automatically each time it makes a change to its attributed string. Subclasses that override or add methods that alter their attributed strings directly should invoke this method after making those changes. The information accumulated with this method is then used in an invocation of processEditing to report the affected portion of the receiver.

mask specifies the nature of the changes. Its value is made by combining these options with the C bitwise OR operator:


Option Meaning
TextStorageEditedAttributes Attributes were added, removed, or changed.
TextStorageEditedCharacters Characters were added, removed, or replaced.

oldRange indicates the extent of characters affected before the change took place. If the TextStorageEditedCharacters bit of mask is set, lengthChange gives the number of characters added to or removed from oldRange (otherwise its value is irrelevant). For example, when replacing "The" with "Several" in the string "The files couldn't be saved", oldRange is {0, 3} and lengthChange is 4.

The methods for querying changes, editedRange and changeInLength, indicate the extent of characters affected after the change. This method expects the characters before the change because that information is readily available as the argument to whatever method performs the change (such as replaceCharactersInRange:withString:).



editedMask

public int editedMask()

Returns the kinds of edits pending for the receiver, as a mask containing either or both of TextStorageEditedAttributes and TextStorageEditedCharacters. Use the C bitwise AND operator to test the mask; testing for equality will fail if additional mask flags are added later. The receiver's delegate and layout managers can use this information to determine the nature of edits in their respective notification methods.

See Also: editedRange, changeInLength



editedRange

public NSRange editedRange()

Returns the range of the receiver to which pending changes have been made, whether of characters or of attributes. The receiver's delegate and layout managers can use this information to determine the nature of edits in their respective notification methods.

See Also: changeInLength, editedMask



ensureAttributesAreFixedInRange

public native void ensureAttributesAreFixedInRange(NSRange range)

Description forthcoming.

fixesAttributesLazily

public native boolean fixesAttributesLazily()

Description forthcoming.

invalidateAttributesInRange

public native void invalidateAttributesInRange(NSRange range)

Description forthcoming.

layoutManagers

public NSArray layoutManagers()

Returns the receiver's NSLayoutManagers.

See Also: addLayoutManager, removeLayoutManager



processEditing

public void processEditing()

Cleans up changes made to the receiver and notifies its delegate and layout managers of changes. This method is automatically invoked in response to an editedInRange message. You should never need to invoke it directly.

This method begins by posting a TextStorageWillProcessEditingNotification to the default notification center (which results in the delegate receiving a textStorageWillProcessEditing message). It then invokes the inherited fixAttributesAfterEditingRange: method to fix up attributes after a batch of editing changes. After this, it posts a TextStorageDidProcessEditingNotification to the default notification center (which results in the delegate receiving a textStorageDidProcessEditing message). Finally, it sends a textStorageChanged message to each of the receiver's NSLayoutManagers using the argument values provided.



removeLayoutManager

public void removeLayoutManager(NSLayoutManager aLayoutManager)

Removes aLayoutManager from the receiver's set of NSLayoutManagers.

See Also: addLayoutManager, layoutManagers



replaceCharactersInRange

public void replaceCharactersInRange( NSRange aRange, String aString)

Description forthcoming.

setAttributesInRange

public void setAttributesInRange( NSDictionary aDictionary, NSRange aRange)

Description forthcoming.

setDelegate

public void setDelegate(Object anObject)

Sets the receiver's delegate to anObject.

See Also: delegate




Methods Implemented By the Delegate


textStorageDidProcessEditing

public abstract void textStorageDidProcessEditing(NSNotification aNotification)

Informs the delegate that an NSTextStorage object has finished processing edits. The text storage object is available by sending object to aNotification, which is always a TextStorageDidProcessEditingNotification. The delegate can use this notification to verify the final state of the text storage object; it can't change the text storage object's characters without leaving it in an inconsistent state, but if necessary it can change attributes. Note that even in this case it's possible to put a text storage object into an inconsistent state-for example by changing the font of a range to one that doesn't support the characters in that range (such as using a Latin font for Kanji text).

textStorageWillProcessEditing

public abstract void textStorageWillProcessEditing(NSNotification aNotification)

Informs the delegate that an NSTextStorage object is about to process edits. The text storage object is available by sending object to aNotification, which is always a TextStorageWillProcessEditingNotification. The delegate can use this notification to verify the changed state of the text storage object, and to make changes to the text storage object's characters or attributes to enforce whatever constraints it establishes (which doesn't result in this message being sent again, however). For example, a code editor application might add a delegate that checks after edits to make sure that all programming language keywords are set in boldface.


Notifications


TextStorageDidProcessEditingNotification

Posted after the NSTextStorage finishes processing edits in processEditing. Observers other than the delegate shouldn't make further changes to the NSTextStorage. This notification contains a notification object but no userInfo dictionary. The notification object is the NSTextStorage object that processed the edits.

TextStorageWillProcessEditingNotification

Posted before the NSTextStorage finishes processing edits in processEditing. Observers other than the delegate shouldn't make further changes to the NSTextStorage. This notification contains a notification object but no userInfo dictionary. The notification object is the NSTextStorage object that is a bout to process the edits.

Table of Contents