Mac Developer Library

Developer

AppKit Framework Reference NSTextStorage Class Reference

Options
Deployment Target:

On This Page
Language:

NSTextStorage

The NSTextStorage class defines the fundamental storage mechanism of TextKit. This class is a semi concrete subclass of NSMutableAttributedString that adds behavior for managing a set of client NSLayoutManager objects. A text storage object notifies its layout managers of changes to its characters or attributes, which lets the layout managers redisplay the text as needed.

An NSTextStorage object can be accessed from any thread of your app, but your app must guarantee access from only one thread at a time.

Subclassing Notes

The NSTextStorage class implements change management (via the beginEditing and endEditing methods), verification of attributes, delegate handling, and layout management notification. The one aspect it does not implement is managing the actual attributed string storage, which subclasses manage by overriding the two NSAttributedString primitives:

- (NSString *)string;

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

Subclasses must also 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 let the parent class know what changes were made.

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

    Declaration

    Swift

    func edited(_ editedMask: NSTextStorageEditActions, range editedRange: NSRange, changeInLength delta: Int)

    Objective-C

    - (void)edited:(NSTextStorageEditActions)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 NSTextStorageEditActions.

    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.

  • Ensures that attributes are fixed in the given range.

    Declaration

    Swift

    func ensureAttributesAreFixedInRange(_ range: NSRange)

    Objective-C

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

  • A Boolean value indicating whether the text storage object fixes attributes lazily. (read-only)

    Declaration

    Swift

    var fixesAttributesLazily: Bool { get }

    Objective-C

    @property(readonly) BOOL fixesAttributesLazily

    Discussion

    When subclassing, the default value of this property is NOfalse, meaning that your subclass fixes attributes immediately when they are changed. The system’s concrete subclass overrides this property and sets it to YEStrue.

    Availability

    Available in OS X v10.0 and later.

  • Invalidates attributes in the specified range.

    Declaration

    Swift

    func invalidateAttributesInRange(_ range: NSRange)

    Objective-C

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

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

    Declaration

    Swift

    func processEditing()

    Objective-C

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

  • A mask describing the kinds of edits pending for the text storage object. (read-only)

    Declaration

    Swift

    var editedMask: NSTextStorageEditActions { get }

    Objective-C

    @property(readonly) NSTextStorageEditActions editedMask

    Discussion

    This property indicates pending changes for attributes, characters, or both. Use the C bitwise AND operator to test the value against the NSTextStorageEditedAttributes or NSTextStorageEditedCharacters constants; testing for equality will fail if additional mask flags are added later. The text storage object’s associated 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.

  • The range of text containing changes. (read-only)

    Declaration

    Swift

    var editedRange: NSRange { get }

    Objective-C

    @property(readonly) NSRange editedRange

    Discussion

    The specified range can reflect changes to characters or attributes. The text storage object’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.

  • The difference between the current length of the edited range and its length before editing began. (read-only)

    Declaration

    Swift

    var changeInLength: Int { get }

    Objective-C

    @property(readonly) NSInteger changeInLength

    Discussion

    This property reflects difference between the current length of the edited range and its length before editing began—that is, before the first call to the beginEditing method or a single call to theedited:range:changeInLength: method. This difference is accumulated with each call to the edited:range:changeInLength: method, until the changes are finally processed.

    The text storage object’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.

  • The text storage contents represented as an array of attribute runs.

    Declaration

    Swift

    var attributeRuns: [NSTextStorage]

    Objective-C

    @property(copy) NSArray <NSTextStorage *> *attributeRuns

    Discussion

    Unless you are dealing with scriptability, you should not use or modify this property directly.

    Availability

    Available in OS X v10.0 and later.

  • The text storage contents represented as an array of paragraphs.

    Declaration

    Swift

    var paragraphs: [NSTextStorage]

    Objective-C

    @property(copy) NSArray <NSTextStorage *> *paragraphs

    Discussion

    Unless you are dealing with scriptability, you should not use or modify this property directly.

    Availability

    Available in OS X v10.0 and later.

  • The text storage contents represented as an array of words.

    Declaration

    Swift

    var words: [NSTextStorage]

    Objective-C

    @property(copy) NSArray <NSTextStorage *> *words

    Discussion

    Unless you are dealing with scriptability, you should not use or modify this property directly.

    Availability

    Available in OS X v10.0 and later.

  • The text storage contents represented as an array of characters.

    Declaration

    Swift

    var characters: [NSTextStorage]

    Objective-C

    @property(copy) NSArray <NSTextStorage *> *characters

    Discussion

    Unless you are dealing with scriptability, you should not use or modify this property directly. 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.

  • font font Property

    The font associated with the text storage.

    Declaration

    Swift

    var font: NSFont?

    Objective-C

    @property(strong) NSFont *font

    Discussion

    Unless you are dealing with scriptability, you should not use or modify this property directly.

    Availability

    Available in OS X v10.0 and later.

  • The color to use when drawing the text.

    Declaration

    Swift

    var foregroundColor: NSColor?

    Objective-C

    @property(strong) NSColor *foregroundColor

    Discussion

    Unless you are dealing with scriptability, you should not use or modify this property directly.

    Availability

    Available in OS X v10.0 and later.

  • Constants indicating the types of changes that were made.

    Declaration

    Swift

    struct NSTextStorageEditActions : OptionSetType { init(rawValue rawValue: UInt) static var EditedAttributes: NSTextStorageEditActions { get } static var EditedCharacters: NSTextStorageEditActions { get } }

    Objective-C

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

    Constants

    • EditedAttributes

      NSTextStorageEditedAttributes

      Attributes were added, removed, or changed.

      Available in OS X v10.11 and later.

    • EditedCharacters

      NSTextStorageEditedCharacters

      Characters were added, removed, or replaced.

      Available in OS X v10.11 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.11 and later.

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

    Declaration

    Swift

    let NSTextStorageDidProcessEditingNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    let NSTextStorageWillProcessEditingNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.