iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference NSTextStorage Class Reference for iOS

Options
Deployment Target:

On This Page
Language:

NSTextStorage

Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 7.0 and later.

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.

  • delegate delegate Property

    The text storage delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSTextStorageDelegate?

    Objective-C

    @property(assign, nonatomic) id< NSTextStorageDelegate > delegate

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • The kinds of edits pending for the receiver.

    Declaration

    Swift

    var editedMask: NSTextStorageEditActions

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • The length delta for the pending changes.

    Declaration

    Swift

    var changeInLength: Int

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var editedRange: NSRange

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Notifies and records a recent change.

    Declaration

    Swift

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

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var fixesAttributesLazily: Bool { get }

    Objective-C

    @property(readonly, nonatomic) BOOL fixesAttributesLazily

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Triggers post-editing operations.

    Declaration

    Swift

    func processEditing()

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Adds a layout manager to the receiver.

    Declaration

    Swift

    func addLayoutManager(_ aLayoutManager: NSLayoutManager)

    Objective-C

    - (void)addLayoutManager:(NSLayoutManager *)aLayoutManager

    Parameters

    aLayoutManager

    The layout manager added to the receiver.

    Discussion

    This method sends setTextStorage: to aLayoutManager with the receiver.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func removeLayoutManager(_ aLayoutManager: NSLayoutManager)

    Objective-C

    - (void)removeLayoutManager:(NSLayoutManager *)aLayoutManager

    Parameters

    aLayoutManager

    The layout manager to remove.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var layoutManagers: [AnyObject] { get }

    Objective-C

    @property(readonly, nonatomic) NSArray *layoutManagers

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

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

    Objective-C

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

    Constants

    • EditedAttributes

      NSTextStorageEditedAttributes

      Attributes were added, removed, or changed.

      Available in iOS 7.0 and later.

    • EditedCharacters

      NSTextStorageEditedCharacters

      Characters were added, removed, or replaced.

      Available in iOS 7.0 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.