NSTextStorage Class Reference for iOS

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 7.0 and later.
Declared in
NSTextStorage.h

Overview

NSTextStorage is a semiconcrete subclass of NSMutableAttributedString that manages a set of client NSLayoutManager objects, 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 Text Kit’s extended text-handling system.

NSTextStorage, NLayoutManager, and NSTextContainer can be accessed from subthreads as long as the app guarantees the access from a single thread.

Subclassing Notes

NSTextStorage implements change management (via beginEditing and endEditing), verification of attributes, delegate handling, and layout management notification. The one aspect it does not implement is managing the actual attributed string storage—this is left up to subclasses which must override the two NSAttributedString primitives:

- (NSString *)string;

- (NSDictionary *)attributesAtIndex:(NSUInteger)location effectiveRange:(NSRangePointer)range;

And subclasses must override two NSMutableAttributedString primitives:

- (void)replaceCharactersInRange:(NSRange)range withString:(NSString *)str;

- (void)setAttributes:(NSDictionary *)attrs range:(NSRange)range;

These primitives should perform the change, then call edited:range:changeInLength: to get everything else to happen.

Tasks

Setting the Delegate

Determining the Nature of Changes

Handling Text Edited Messages

Handling Layout Managers

Properties

changeInLength

The length delta for the pending changes.

@property(nonatomic) NSInteger changeInLength
Discussion

This property provides information about the current editing status, which can be especially useful when there are outstanding beginEditing calls or during processEditing.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

delegate

The text storage delegate.

@property(assign, nonatomic) id<NSTextStorageDelegate> delegate
Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

editedMask

The kinds of edits pending for the receiver.

@property(nonatomic) NSTextStorageEditActions editedMask
Discussion

Indicates pending changes for attributes, characters, or both. Use the C bitwise AND operator to test the mask using NSTextStorageEditedAttributes and NSTextStorageEditedCharacters (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

editedRange

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

@property(nonatomic) 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.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

fixesAttributesLazily

Indicates whether the receiver fixes attributes lazily. (read-only)

@property(readonly, nonatomic) BOOL fixesAttributesLazily
Discussion

By default, custom NSTextStorage subclasses are not lazy, but the provided concrete subclass is lazy by default.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

layoutManagers

The receiver’s layout managers. (read-only)

@property(readonly, nonatomic) NSArray *layoutManagers
Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

Instance Methods

addLayoutManager:

Adds a layout manager to the receiver.

- (void)addLayoutManager:(NSLayoutManager *)aLayoutManager
Parameters
aLayoutManager

The layout manager added to the receiver.

Discussion

This method sends setTextStorage: to aLayoutManager with the receiver.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

edited:range:changeInLength:

Notifies and records a recent change.

- (void)edited:(NSTextStorageEditActions)editedMask range:(NSRange)editedRange changeInLength:(NSInteger)delta
Parameters
editedMask

The edit action performed.

editedRange

The range in the original string (before the edit).

delta

The length delta for the editing changes.

Discussion

If there are no outstanding beginEditing calls, this method calls processEditing to trigger post-editing processes. This method must be called by the primitives after changes are made if subclassed and overridden.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

ensureAttributesAreFixedInRange:

Ensures that attributes are fixed in the given range.

- (void)ensureAttributesAreFixedInRange:(NSRange)range
Parameters
range

The range of characters whose attributes might be examined.

Discussion

An NSTextStorage object using lazy attribute fixing is required to call this method before accessing any attributes within range. 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.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

invalidateAttributesInRange:

Invalidates attributes in the specified range.

- (void)invalidateAttributesInRange:(NSRange)range
Parameters
range

The range of characters whose attributes should be invalidated.

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.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

processEditing

Triggers post-editing operations.

- (void)processEditing
Discussion

Sends out the delegate message textStorage:WillProcessEditing:range:changeInLength:, fixes attributes, sends out textStorage:didProcessEditing:range:changeInLength:, and notifies the layout managers of the change with the processEditingForTextStorage:edited:range:changeInLength:invalidatedRange: method. Invoked from edited:range:changeInLength: or endEditing.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

removeLayoutManager:

Removes a layout manager from the receiver’s set of layout managers.

- (void)removeLayoutManager:(NSLayoutManager *)aLayoutManager
Parameters
aLayoutManager

The layout manager to remove.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSTextStorage.h

Constants

Change notifications

These constants are used in edited:range:changeInLength:.

typedef enum : NSUInteger {
   NSTextStorageEditedAttributes = (1 << 0),
   NSTextStorageEditedCharacters = (1 << 1)
} NSTextStorageEditActions;
Constants
NSTextStorageEditedAttributes

Attributes were added, removed, or changed.

Available in iOS 7.0 and later.

Declared in NSTextStorage.h.

NSTextStorageEditedCharacters

Characters were added, removed, or replaced.

Available in iOS 7.0 and later.

Declared in NSTextStorage.h.

Discussion

These values are also OR'ed together in notifications to inform instances of NSLayoutManager of editing changes. See textStorage:edited:range:changeInLength:invalidatedRange:.

Notifications

NSTextStorageDidProcessEditingNotification

Posted after a text storage finishes processing edits in processEditing.

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

Availability
Declared In
NSTextStorage.h

NSTextStorageWillProcessEditingNotification

Posted before a text storage finishes processing edits in processEditing.

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

Availability
Declared In
NSTextStorage.h