Mac Developer Library

Developer

AppKit Framework Reference NSTextStorage Class Reference

Options
Deployment Target:

On This Page
Language:

NSTextStorage

Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.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 Application Kit’s extended text-handling system.

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

    Declaration

    Swift

    func edited(_ mask: Int, range oldRange: NSRange, changeInLength lengthChange: Int)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns whether the receiver fixes attributes lazily.

    Declaration

    Swift

    var fixesAttributesLazily: Bool { get }

    Objective-C

    @property(readonly) BOOL fixesAttributesLazily

    Return Value

    YEStrue if the text storage fixes attributes lazily, NOfalse otherwise.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the kinds of edits pending for the receiver

    Declaration

    Swift

    var editedMask: Int { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var editedRange: NSRange { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var changeInLength: Int { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSTextStorageDelegate?

    Objective-C

    @property(assign) id<NSTextStorageDelegate> delegate

    Parameters

    anObject

    The new delegate.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – delegate

  • Returns the receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSTextStorageDelegate?

    Objective-C

    @property(assign) id<NSTextStorageDelegate> delegate

    Return Value

    The receiver's delegate.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an array of the receiver’s attribute runs.

    Declaration

    Swift

    var attributeRuns: [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s attribute runs.

    Declaration

    Swift

    var attributeRuns: [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var characters: [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the text storage's text.

    Declaration

    Swift

    var characters: [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s font.

    Declaration

    Swift

    var font: NSFont?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the text storage's font.

    Declaration

    Swift

    var font: NSFont?

    Objective-C

    @property(strong) NSFont *font

    Parameters

    font

    The new font.

    Special Considerations

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the text storage's foreground color.

    Declaration

    Swift

    var foregroundColor: NSColor?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the text storage's foreground color.

    Declaration

    Swift

    var foregroundColor: NSColor?

    Objective-C

    @property(strong) NSColor *foregroundColor

    Parameters

    color

    The new foreground color.

    Special Considerations

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an array of the text storage's paragraphs.

    Declaration

    Swift

    var paragraphs: [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the text storage's paragraphs.

    Declaration

    Swift

    var paragraphs: [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an array of the text storage's words.

    Declaration

    Swift

    var words: [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the text storage's words.

    Declaration

    Swift

    var words: [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    static var Attributes: NSTextStorageEditedOptions { get } static var Characters: NSTextStorageEditedOptions { get }

    Objective-C

    enum { NSTextStorageEditedAttributes = 1, NSTextStorageEditedCharacters = 2 };

    Constants

    • Attributes

      NSTextStorageEditedAttributes

      Attributes were added, removed, or changed.

      Available in OS X v10.0 and later.

    • Characters

      NSTextStorageEditedCharacters

      Characters were added, removed, or replaced.

      Available in OS X v10.0 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:.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.