NSTextStorage Class Reference

Inherits from
NSMutableAttributedString : NSAttributedString : NSObject
Conforms to
NSCoding (NSAttributedString)
NSCopying (NSAttributedString)
NSMutableCopying (NSAttributedString)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSTextStorage.h
NSTextStorageScripting.h
Companion guides
Text System Overview
Text System Storage Layer Overview
Cocoa Scripting Guide
Related sample code

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 Application Kit’s extended text-handling system.

Tasks

Managing NSLayoutManager Objects

Handling Text Edited Messages

Determining the Nature of Changes

Determining the Extent of Changes

Setting the Delegate

Getting and Setting Scriptable Properties

Instance Methods

addLayoutManager:

Adds a layout manager to the receiver’s set of layout managers.

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

The layout manager to add.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSTextStorage.h

attributeRuns

Returns an array of the receiver’s attribute runs.

- (NSArray *)attributeRuns
Return Value

An array of the receiver’s attribute runs.

Special Considerations

Unless you are dealing with scriptability, you should not invoke this method directly.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.h

changeInLength

Returns the difference between the current length of the edited range and its length before editing began.

- (NSInteger)changeInLength
Return Value

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 edited:range:changeInLength: message.

Discussion

This difference is accumulated with each invocation of edited:range:changeInLength:, 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.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTextStorage.h

characters

Returns the receiver’s text as an array of characters.

- (NSArray *)characters
Special Considerations

Do not use this method unless you are dealing directly with scriptability. For indexed access to characters, use NSAttributedString’s length method to access the string, and NSString’s characterAtIndex: method to access the individual characters.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.h

delegate

Returns the receiver’s delegate.

- (id)delegate
Return Value

The receiver's delegate.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTextStorage.h

edited:range:changeInLength:

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

- (void)edited:(NSUInteger)mask range:(NSRange)oldRange changeInLength:(NSInteger)lengthChange
Parameters
mask

A mask specifying the nature of the changes. The value is made by combining with the C bitwise OR operator the options described in “Change notifications”.

oldRange

The extent of characters affected before the change took place.

lengthChange

The number of characters added to or removed from oldRange. If no characters where edited as noted by mask, its value is irrelevant and undefined. For example, when replacing “The” with “Several” in the string “The files couldn’t be saved”, oldRange is {0, 3} and lengthChange is 4.

Discussion

This method invokes processEditing if there are no outstanding beginEditing calls. 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 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:).

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTextStorage.h

editedMask

Returns the kinds of edits pending for the receiver

- (NSUInteger)editedMask
Return Value

A mask describing the kinds of edits pending for the receiver.

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.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTextStorage.h

editedRange

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

- (NSRange)editedRange
Return Value

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

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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
Declared In
NSTextStorage.h

fixesAttributesLazily

Returns whether the receiver fixes attributes lazily.

- (BOOL)fixesAttributesLazily
Return Value

YES if the text storage fixes attributes lazily, NO otherwise.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorage.h

font

Returns the receiver’s font.

- (NSFont *)font
Return Value

The receiver's font.

Discussion

In OS X v10.5 and later, if the font has not been set, this method and font-related scripting commands assume Helvetica 12.

Special Considerations

Unless you are dealing with scriptability, you should not invoke this method directly.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.h

foregroundColor

Returns the text storage's foreground color.

- (NSColor *)foregroundColor
Return Value

The text storage's foreground color.

Special Considerations

Unless you are dealing with scriptability, you should not invoke this method directly.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.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 OS X v10.0 and later.
See Also
Declared In
NSTextStorage.h

layoutManagers

Returns the receiver’s layout managers.

- (NSArray *)layoutManagers
Return Value

The receiver's layout managers.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSTextStorage.h

paragraphs

Returns an array of the text storage's paragraphs.

- (NSArray *)paragraphs
Return Value

An array of the text storage's paragraphs.

Special Considerations

Unless you are dealing with scriptability, you should not invoke this method directly.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.h

processEditing

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

- (void)processEditing
Discussion

This method is automatically invoked in response to an edited:range:changeInLength: message or an endEditing message if edits were made within the scope of a beginEditing block. You should never need to invoke it directly.

This method begins by posting an NSTextStorageWillProcessEditingNotification to the default notification center (which results in the delegate receiving a textStorageWillProcessEditing: message). Then it fixes attributes. 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 layout managers using the argument values provided.

Availability
  • Available in OS X v10.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 OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSTextStorage.h

setAttributeRuns:

Sets the receiver’s attribute runs.

- (void)setAttributeRuns:(NSArray *)attributeRuns
Parameters
attributeRuns

The array of attribute runs to set.

Special Considerations

Unless you are dealing with scriptability, you should not invoke this method directly.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.h

setCharacters:

Sets the text storage's text.

- (void)setCharacters:(NSArray *)characters
Parameters
characters

The characters to set as the text of the text storage.

Special Considerations

Do not use this method if you are not dealing directly with scriptability. Use NSMutableAttributedString’s mutableString method to return a string object that will be tracked by the corresponding attributed string for modifications.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)anObject
Parameters
anObject

The new delegate.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTextStorage.h

setFont:

Sets the text storage's font.

- (void)setFont:(NSFont *)font
Parameters
font

The new font.

Special Considerations

Unless you are dealing with scriptability, you should not invoke this method directly.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTextStorageScripting.h

setForegroundColor:

Sets the text storage's foreground color.

- (void)setForegroundColor:(NSColor *)color
Parameters
color

The new foreground color.

Special Considerations

Unless you are dealing with scriptability, you should not invoke this method directly.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.h

setParagraphs:

Sets the text storage's paragraphs.

- (void)setParagraphs:(NSArray *)paragraphs
Parameters
paragraphs

An array of strings to set as the text storage's paragraphs.

Special Considerations

Unless you are dealing with scriptability, you should not invoke this method directly.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.h

setWords:

Sets the text storage's words.

- (void)setWords:(NSArray *)words
Parameters
words

An array of strings to set as the text storage's words.

Special Considerations

Unless you are dealing with scriptability, you should not invoke this method directly.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.h

words

Returns an array of the text storage's words.

- (NSArray *)words
Return Value

An array of the text storage's words.

Special Considerations

Unless you are dealing with scriptability, you should not invoke this method directly.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextStorageScripting.h

Constants

Change notifications

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

enum {
   NSTextStorageEditedAttributes = 1,
   NSTextStorageEditedCharacters = 2
};
Constants
NSTextStorageEditedAttributes

Attributes were added, removed, or changed.

Available in OS X v10.0 and later.

Declared in NSTextStorage.h.

NSTextStorageEditedCharacters

Characters were added, removed, or replaced.

Available in OS X v10.0 and later.

Declared in NSTextStorage.h.

Discussion

These values are also OR'ed together in notifications to inform instances of NSLayoutManager was changed—see textStorage:edited:range:changeInLength:invalidatedRange:.

Declared In
NSTextStorage.h

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


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-06-11)

Did this document help you? Yes It's good, but... Not helpful...