- Inherits from:
- NSMutableAttributedString : NSAttributedString : NSObject
- Conforms to:
- NSObject
- (NSObject)
Declared in:
- AppKit/NSTextStorage.h
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.
Like an abstract class of a class cluster, allocating and initializing an NSTextStorage actually produces an instance of a private subclass. You can use any of NSAttributedString and NSMutableAttributedString's initialization methods to create an NSTextStorage object. 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 edited:range:changeInLength: 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.
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, override init and define its own initialization methods, 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 edited:range:changeInLength: 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
- - edited:range:changeInLength:
- - ensureAttributesAreFixedInRange:
- - fixesAttributesLazily
- - invalidateAttributesInRange:
- - processEditing
- Determining the nature of changes
- - editedMask
- Determining the extent of changes
- - editedRange
- - changeInLength
- Setting the delegate
- - setDelegate:
- - delegate
- (void)addLayoutManager:(NSLayoutManager
*)aLayoutManager
See Also: - removeLayoutManager:, - layoutManagers
- (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
- (id)delegate
See Also: - setDelegate:
- (void)edited:(unsigned)mask
range:(NSRange)oldRange
changeInLength:(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:).
- (unsigned 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
- (NSRange)editedRange
See Also: - changeInLength, - editedMask
- (void)ensureAttributesAreFixedInRange:(NSRange)range
- (BOOL)fixesAttributesLazily
- (void)invalidateAttributesInRange:(NSRange)range
- (NSArray *)layoutManagers
See Also: - addLayoutManager:, - removeLayoutManager:
- (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.
- (void)removeLayoutManager:(NSLayoutManager
*)aLayoutManager
See Also: - addLayoutManager:, - layoutManagers
- (void)setDelegate:(id)anObject
See Also: - delegate
- (void)textStorageDidProcessEditing:(NSNotification
*)aNotification
- (void)textStorageWillProcessEditing:(NSNotification
*)aNotification