Inherits from: NSMutableAttributedString : NSAttributedString : NSObject
Package: com.apple.yellow.application
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 endEditing 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.
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.
- Managing NSLayoutManagers
- addLayoutManager
- removeLayoutManager
- layoutManagers
- Handling text edited messages
- editedInRange
- endEditing
- processEditing
- Determining the nature of changes
- editedMask
- Determining the extent of changes
- editedRange
- changeInLength
- Setting the delegate
- setDelegate
- delegate
public NSTextStorage(String aString)
public NSTextStorage(String aString, NSDictionary aDictionary)
public NSTextStorage(NSAttributedString anAttributedString)
public NSTextStorage(URL aURL, NSMutableDictionary aDictionary)
public NSTextStorage(NSData data, NSMutableDictionary aDictionary)
public NSTextStorage(Object anObject, NSMutableDictionary aDictionary)
public NSTextStorage(NSData data, Object anObject, NSMutableDictionary aDictionary)
public NSTextStorage(String aString, NSMutableDictionary aDictionary)
public void addLayoutManager(NSLayoutManager aLayoutManager)
See Also: removeLayoutManager, layoutManagers
public int changeInLength()
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
public Object delegate()
See Also: setDelegate
public void editedInRange(int mask, NSRange oldRange, int lengthChange)
mask specifies the nature of the changes. Its value is made by combining these options with the C bitwise OR operator:
Option | Meaning |
NSTextStorageEditedAttributes |
Attributes were added, removed, or changed. |
NSTextStorageEditedCharacters |
Characters were added, removed, or replaced. |
oldRange indicates
the extent of characters affected before the change took place. If
the NSTextStorageEditedCharacters
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:).
public int editedMask()
NSTextStorageEditedAttributes
and NSTextStorageEditedCharacters
. 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
public NSRange editedRange()
See Also: changeInLength, editedMask
- (void)endEditing
public NSArray layoutManagers()
See Also: addLayoutManager, removeLayoutManager
public void processEditing()
This method begins by posting an NSTextStorageWillProcessEditingNotification 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 an NSTextStorageDidProcessEditingNotification to the default notification center (which results in the delegate receiving a textStorageDidProcessEditing message). Finally, it sends a textStorage:edited:range:changeInLength:invalidatedRange: message to each of the receiver's NSLayoutManagers using the argument values provided.
public void removeLayoutManager(NSLayoutManager aLayoutManager)
See Also: addLayoutManager, layoutManagers
public void replaceCharactersInRange(NSRange aRange, String aString)
public void setAttributesInRange(NSDictionary aNictionary, NSRange aRange)
public void setDelegate(Object anObject)
See Also: delegate
public abstract void textStorageDidProcessEditing(NSNotification aNotification)
public abstract void textStorageWillProcessEditing(NSNotification aNotification)
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.
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.