---

NSTextStorage

Overview

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

Tasks

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

Processing edit

• textStorageWillProcessEditing  delegate method
• textStorageDidProcessEditing  delegate method

Instance Methods

addLayoutManager

Adds aLayoutManager to the receiver’s set of NSLayoutManagers.

public void addLayoutManager(NSLayoutManager aLayoutManager)

See Also

• removeLayoutManager
• layoutManagers

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).

public int changeInLength()

Discussion

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

Returns the receiver’s delegate.

public Object delegate()

See Also

• setDelegate

editedInRange

Tracks changes made to the receiver, allowing the NSTextStorage to record the full extent of changes made.

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

Discussion

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; otherwise you should not invoke this method. The information accumulated with this method is then used in an invocation of processEditing to report the affected portion of the receiver.

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

The oldRange argument 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).

editedMask

Returns the kinds of edits pending for the receiver, as a mask containing either or both of TextStorageEditedAttributes and TextStorageEditedCharacters.

public int editedMask()

Discussion

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

Returns the range of the receiver to which pending changes have been made, whether of characters or of attributes.

public NSRange editedRange()

Discussion

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

An NSTextStorage using lazy attribute fixing is required to call this method before accessing any attributes within range.

public void ensureAttributesAreFixedInRange(NSRange range)

Discussion

This method gives attribute fixing a chance to occur if necessary. NSTextStorage subclasses wishing to support laziness must call this method from all attribute accessors they implement.

See Also

• fixesAttributesLazily
• invalidateAttributesInRange

fixesAttributesLazily

Returns whether the receiver fixes attributes lazily.

public boolean fixesAttributesLazily()

Discussion

This method can control whether an instance fixes attributes lazily by returning true. By default, custom NSTextStorage subclasses are not lazy, but the provided concrete subclass is lazy by default.

invalidateAttributesInRange

Invalidates attributes in range.

public void invalidateAttributesInRange(NSRange range)

Discussion

Called from processEditing to invalidate attributes when the text storage changes. If the receiver is not lazy, this method simply calls fixAttributesInRange. If lazy attribute fixing is in effect, this method instead records the range needing fixing.

See Also

• ensureAttributesAreFixedInRange
• fixesAttributesLazily

layoutManagers

Returns the receiver’s NSLayoutManagers.

public NSArray layoutManagers()

See Also

• addLayoutManager
• removeLayoutManager

processEditing

Cleans up changes made to the receiver and notifies its delegate and layout managers of changes.

public void processEditing()

Discussion

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 fixAttributesInRange 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

Removes aLayoutManager from the receiver’s set of NSLayoutManagers.

public void removeLayoutManager(NSLayoutManager aLayoutManager)

See Also

• addLayoutManager
• layoutManagers

replaceCharactersInRange

Replaces the characters in aRange with the characters of aString.

public void replaceCharactersInRange(NSRange aRange, String aString)

Discussion

The new characters inherit the attributes of the first replaced character from aRange. Where the length of aRange is 0, the new characters inherit the attributes of the character preceding aRange if it has any, otherwise of the character following aRange.

Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

• deleteCharactersInRange (NSMutableAttributedString)

setAttributesInRange

Sets the attributes for the characters in aRange to the attributes listed in attributes.

public void setAttributesInRange(NSDictionary attributes, NSRange aRange)

Discussion

These new attributes replace any attributes previously associated with the characters in aRange. Throws a RangeException if any part of aRange lies beyond the end of the receiver’s characters.

See Also

• addAttributesInRange (NSMutableAttributedString)
• removeAttributeInRange (NSMutableAttributedString)

setDelegate

Sets the receiver’s delegate to anObject.

public void setDelegate(Object anObject)

See Also

• delegate

Delegate Methods

textStorageDidProcessEditing

Informs the delegate that an NSTextStorage object has finished processing edits.

public abstract void textStorageDidProcessEditing(NSNotification aNotification)

Discussion

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

Informs the delegate that an NSTextStorage object is about to process edits.

public abstract void textStorageWillProcessEditing(NSNotification aNotification)

Discussion

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).

Notifications

TextStorageDidProcessEditingNotification

Posted after an NSTextStorage finishes processing edits in processEditing.

Observers other than the delegate shouldn’t make further changes to the NSTextStorage. The notification object is the NSTextStorage object that processed the edits. This notification does not contain a userInfo dictionary.

TextStorageWillProcessEditingNotification

Posted before an NSTextStorage finishes processing edits in processEditing.

Observers other than the delegate shouldn’t make further changes to the NSTextStorage. The notification object is the NSTextStorage object that is about to process the edits. This notification does not contain a userInfo dictionary.

---