Mac Developer Library

Developer

AppKit Framework Reference NSTextView Class Reference

Options
Deployment Target:

On This Page
Language:

NSTextView

The NSTextView class is the front-end class to the Application Kit’s text system. The class draws the text managed by the back-end components and handles user events to select and modify its text. NSTextView is the principal means to obtain a text object that caters to almost all needs for displaying and managing text at the user interface level. While NSTextView is a subclass of the NSText class—which declares the most general Cocoa interface to the text system—NSTextView adds major features beyond the capabilities of NSText.

Your applications will use the NSTextView class over the NSText class. It is also important to remember that NSTextView conforms to a large number of protocols as listed above. The methods of these protocols are available to instances of the NSTextView class.

Be sure to read Cocoa Text Architecture Guide and Text System User Interface Layer Programming Guide to fully understand how to use this class.

About Delegate Methods

The NSTextView class communicates with its delegate through methods declared both by the NSTextViewDelegate Protocol and by its superclass’s protocol, NSTextDelegate Protocol. All delegation messages come from the first text view.

  • Initializes a text view.

    Declaration

    Swift

    init(frame frameRect: NSRect, textContainer container: NSTextContainer?)

    Objective-C

    - (instancetype)initWithFrame:(NSRect)frameRect textContainer:(NSTextContainer *)aTextContainer

    Parameters

    frameRect

    The frame rectangle of the text view.

    aTextContainer

    The text container of the text view.

    Return Value

    An initialized text view.

    Discussion

    This method is the designated initializer for NSTextView objects.

    Unlike initWithFrame:, which builds up an entire group of text-handling objects, you use this method after you’ve created the other components of the text-handling system—a text storage object, a layout manager, and a text container. Assembling the components in this fashion means that the text storage, not the text view, is the principal owner of the component objects.

    Availability

    Available in OS X v10.0 and later.

  • Initializes a text view.

    Declaration

    Swift

    convenience init(frame frameRect: NSRect)

    Objective-C

    - (instancetype)initWithFrame:(NSRect)frameRect

    Parameters

    frameRect

    The frame rectangle of the text view.

    Return Value

    An initialized text view.

    Discussion

    This method creates the entire collection of objects associated with a text view—its text container, layout manager, and text storage—and invokes initWithFrame:textContainer:.

    This method creates the text web in such a manner that the text view is the principal owner of the objects in the web.

    Availability

    Available in OS X v10.0 and later.

  • Registers send and return types for the Services facility.

    Declaration

    Swift

    class func registerForServices()

    Objective-C

    + (void)registerForServices

    Discussion

    This method is invoked automatically when the first instance of a text view is created; you should never need to invoke it directly.

    Subclasses of NSTextView that wish to add support for new service types should override registerForServices to call super and then register their own new types.

    Availability

    Available in OS X v10.0 and later.

  • Marks the receiver as requiring display.

    Declaration

    Swift

    func setNeedsDisplayInRect(_ rect: NSRect, avoidAdditionalLayout flag: Bool)

    Objective-C

    - (void)setNeedsDisplayInRect:(NSRect)aRect avoidAdditionalLayout:(BOOL)flag

    Parameters

    aRect

    The rectangle in which display is required.

    flag

    A value of YEStrue causes the receiver to not perform any layout, even if this means that portions of the text view remain empty. Otherwise the receiver performs at least as much layout as needed to display aRect.

    Discussion

    NSTextView overrides the NSViewsetNeedsDisplayInRect: method to invoke this method with a flag argument of NOfalse.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean that determines whether the receiver should draw its insertion point. (read-only)

    Declaration

    Swift

    var shouldDrawInsertionPoint: Bool { get }

    Objective-C

    @property(readonly) BOOL shouldDrawInsertionPoint

    Discussion

    YEStrue if the receiver should draw its insertion point, NOfalse otherwise.

    Availability

    Available in OS X v10.0 and later.

  • Draws or erases the insertion point.

    Declaration

    Swift

    func drawInsertionPointInRect(_ rect: NSRect, color color: NSColor, turnedOn flag: Bool)

    Objective-C

    - (void)drawInsertionPointInRect:(NSRect)aRect color:(NSColor *)aColor turnedOn:(BOOL)flag

    Parameters

    aRect

    The rectangle in which to draw the insertion point.

    aColor

    The color with which to draw the insertion point.

    flag

    YEStrue to draw the insertion point, NOfalse to erase it.

    Special Considerations

    The focus must be locked on the receiver when this method is invoked. You should not need to invoke this method directly.

    Availability

    Available in OS X v10.0 and later.

  • Draws the background of the text view.

    Declaration

    Swift

    func drawViewBackgroundInRect(_ rect: NSRect)

    Objective-C

    - (void)drawViewBackgroundInRect:(NSRect)rect

    Parameters

    rect

    The rectangle in which to draw the background.

    Discussion

    Subclasses can override this method to perform additional drawing behind the text.

    Availability

    Available in OS X v10.3 and later.

  • Attempts to set the frame size as if by user action.

    Declaration

    Swift

    func setConstrainedFrameSize(_ desiredSize: NSSize)

    Objective-C

    - (void)setConstrainedFrameSize:(NSSize)desiredSize

    Parameters

    desiredSize

    The new desired size.

    Discussion

    This method respects the receiver’s existing minimum and maximum sizes and by whether resizing is permitted.

    Availability

    Available in OS X v10.0 and later.

    See Also

    minSize (NSText)
    maxSize (NSText)
    isHorizontallyResizable (NSText)
    isVerticallyResizable (NSText)

  • Releases the drag information still existing after the dragging session has completed.

    Declaration

    Swift

    func cleanUpAfterDragOperation()

    Objective-C

    - (void)cleanUpAfterDragOperation

    Discussion

    Subclasses may override this method to clean up any additional data structures used for dragging. In your overridden method, be sure to invoke super’s implementation of this method.

    Availability

    Available in OS X v10.0 and later.

  • Causes a temporary highlighting effect to appear around the visible portion (or portions) of the specified range.

    Declaration

    Swift

    func showFindIndicatorForRange(_ charRange: NSRange)

    Objective-C

    - (void)showFindIndicatorForRange:(NSRange)charRange

    Parameters

    charRange

    The character range around which indicators appear.

    Discussion

    This method supports lozenge-style indication of find results. The indicators automatically disappear after a certain period of time, or when the method is called again, or when any of a number of changes occur to the view (such as changes to text, view size, or view position).

    This method does not itself scroll the specified range to be visible; any desired scrolling should be done before this method is called, first, because the method acts only on the visible portion of the specified range, and, second, because scrolling causes the indicators to disappear. Calling this method with a zero-length range always removes any existing indicators.

    Availability

    Available in OS X v10.5 and later.

  • Inserts aString into the receiver’s text at the insertion point if there is one, otherwise replacing the selection.

    Declaration

    Swift

    func insertText(_ insertString: AnyObject)

    Objective-C

    - (void)insertText:(id)aString

    Parameters

    aString

    The string to insert. aString can be either an NSString object or an NSAttributedString object.

    Discussion

    The inserted text is assigned the current typing attributes.

    This method is the means by which text typed by the user enters an NSTextView. See the NSInputManager class and NSTextInput protocol specifications for more information.

    This method is the entry point for inserting text typed by the user and is generally not suitable for other purposes. Programmatic modification of the text is best done by operating on the text storage directly. Because this method pertains to the actions of the user, the text view must be editable for the insertion to work.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

    See Also

    typingAttributes

  • An array of locale identifiers representing input sources that are allowed to be enabled when the receiver has the keyboard focus.

    Declaration

    Swift

    var allowedInputSourceLocales: [String]?

    Objective-C

    @property(copy) NSArray <NSString *> *allowedInputSourceLocales

    Discussion

    You can use the meta-locale identifier, NSAllRomanInputSourcesLocaleIdentifier, to specify input sources that are limited for Roman script editing.

    Availability

    Available in OS X v10.5 and later.

  • A Boolean that indicates whether the receiver allows undo.

    Declaration

    Swift

    var allowsUndo: Bool

    Objective-C

    @property BOOL allowsUndo

    Discussion

    YEStrue if the receiver allows undo, otherwise NOfalse.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean that controls whether the text views sharing the receiver’s layout manager allow the user to edit text.

    Declaration

    Swift

    var editable: Bool

    Objective-C

    @property(getter=isEditable) BOOL editable

    Discussion

    YEStrue to allow the user to edit text and attributes of all text views sharing the receiver's layout manager, NOfalse otherwise.

    If a text view is made editable, it’s also made selectable. Text views are editable by default.

    Availability

    Available in OS X v10.10 and later.

    See Also

    selectable

  • A Boolean that controls whether the text views sharing the receiver’s layout manager allow the user to select text.

    Declaration

    Swift

    var selectable: Bool

    Objective-C

    @property(getter=isSelectable) BOOL selectable

    Discussion

    YEStrue to allow the user to select text of all text views sharing the receiver's layout manager; otherwise, NOfalse.

    If a text view is made not selectable, it’s also made not editable, and buttons on the Find panel are dimmed. Text views are by default both editable and selectable

    Availability

    Available in OS X v10.10 and later.

    See Also

    editable

  • A Boolean that controls whether the text views sharing the receiver’s layout manager behave as field editors.

    Declaration

    Swift

    var fieldEditor: Bool

    Objective-C

    @property(getter=isFieldEditor) BOOL fieldEditor

    Discussion

    Field editors interpret Tab, Shift-Tab, and Return (Enter) as cues to end editing and possibly to change the first responder. Non-field editors instead accept these characters as text input. See Text Fields, Text Views, and the Field Editor for more information on field editors. By default, text views don’t behave as field editors.

    Availability

    Available in OS X v10.10 and later.

  • A Boolean that controls whether the text views sharing the receiver’s layout manager allow the user to apply attributes to specific ranges of text.

    Declaration

    Swift

    var richText: Bool

    Objective-C

    @property(getter=isRichText) BOOL richText

    Discussion

    Text fields that don't allow rich text also don't accept dragged files. By default, text views let the user apply multiple attributes to text, but don’t accept dragged files.

    Availability

    Available in OS X v10.10 and later.

  • A Boolean that controls whether the text views sharing the receiver’s layout manager allow the user to import files by dragging.

    Declaration

    Swift

    var importsGraphics: Bool

    Objective-C

    @property BOOL importsGraphics

    Discussion

    YEStrue to allow the user to import files by dragging onto the text views sharing the receiver’s layout manager, NOfalse otherwise.

    Text views that are set to accept dragged files are also set to allow rich text. By default, text views don’t accept dragged files but do allow rich text.

    Availability

    Available in OS X v10.0 and later.

    See Also

    textStorage
    richText
    attributedStringWithAttachment: (NSAttributedString Additions)
    insertAttributedString:atIndex: (NSMutableAttributedString)

  • Sets the base writing direction of a range of text.

    Declaration

    Swift

    func setBaseWritingDirection(_ writingDirection: NSWritingDirection, range range: NSRange)

    Objective-C

    - (void)setBaseWritingDirection:(NSWritingDirection)writingDirection range:(NSRange)range

    Parameters

    writingDirection

    The new writing direction for the text in range.

    range

    The range of text that will have the new writing direction.

    Discussion

    Invoke this method to change the base writing direction from left-to-right to right-to-left for languages like Hebrew and Arabic, for example.

    This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges:replacementStrings: or shouldChangeTextInRange:replacementString: to include this method in an undoable action.

    Availability

    Available in OS X v10.4 and later.

  • Changes the base writing direction of a paragraph between left-to-right and right-to-left.

    Deprecation Statement

    This method is deprecated in favor of the NSResponder class’s methods makeBaseWritingDirectionNatural:, makeBaseWritingDirectionLeftToRight:, and makeBaseWritingDirectionRightToLeft:.

    Declaration

    Objective-C

    - (void)toggleBaseWritingDirection:(id)sender

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.6.

  • The receiver’s default paragraph style.

    Declaration

    Swift

    @NSCopying var defaultParagraphStyle: NSParagraphStyle?

    Objective-C

    @property(copy) NSParagraphStyle *defaultParagraphStyle

    Availability

    Available in OS X v10.3 and later.

  • Adds the outline attribute to the selected text attributes if absent; removes the attribute if present.

    Declaration

    Swift

    func outline(_ sender: AnyObject?)

    Objective-C

    - (void)outline:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Discussion

    If there is a selection and the first character of the selected range has a non-zero stroke width, or if there is no selection and the typing attributes have a non-zero stroke width, then the stroke width is removed; otherwise the value of NSStrokeWidthAttributeName is set to the default value for outline (3.0).

    Operates on the selected range if the receiver contains rich text. For plain text the range is the entire contents of the receiver.

    Availability

    Available in OS X v10.3 and later.

  • Indicates whether image attachments should permit editing of their images.

    Declaration

    Swift

    var allowsImageEditing: Bool

    Objective-C

    @property BOOL allowsImageEditing

    Discussion

    YEStrue if image editing is allowed; otherwise, NOfalse.

    For image editing to be allowed, the text view must be editable and the text attachment cell must support image editing.

    Availability

    Available in OS X v10.5 and later.

  • A Boolean that enables and disables automatic quotation mark substitution.

    Declaration

    Swift

    var automaticQuoteSubstitutionEnabled: Bool

    Objective-C

    @property(getter=isAutomaticQuoteSubstitutionEnabled) BOOL automaticQuoteSubstitutionEnabled

    Discussion

    If YEStrue, automatic quotation mark substitution is enabled; if NOfalse, it is disabled.

    Automatic quote substitution causes ASCII quotation marks and apostrophes to be automatically replaced, on a context-dependent basis, with more typographically accurate symbols.

    Availability

    Available in OS X v10.5 and later.

  • Changes the state of automatic quotation mark substitution from enabled to disabled and vice versa.

    Declaration

    Swift

    func toggleAutomaticQuoteSubstitution(_ sender: AnyObject?)

    Objective-C

    - (void)toggleAutomaticQuoteSubstitution:(id)sender

    Parameters

    sender

    The control sending the message; may be nil.

    Discussion

    Automatic quote substitution causes ASCII quotation marks and apostrophes to be automatically replaced, on a context-dependent basis, with more typographically accurate symbols.

    Availability

    Available in OS X v10.5 and later.

  • A Boolean that enables or disables automatic link detection.

    Declaration

    Swift

    var automaticLinkDetectionEnabled: Bool

    Objective-C

    @property(getter=isAutomaticLinkDetectionEnabled) BOOL automaticLinkDetectionEnabled

    Discussion

    If YEStrue, automatic link detection is enabled; if NOfalse, it is disabled.

    Automatic link detection causes strings representing URLs typed in the view to be automatically made into links to those URLs.

    Availability

    Available in OS X v10.5 and later.

  • Changes the state of automatic link detection from enabled to disabled and vice versa.

    Declaration

    Swift

    func toggleAutomaticLinkDetection(_ sender: AnyObject?)

    Objective-C

    - (void)toggleAutomaticLinkDetection:(id)sender

    Parameters

    sender

    The control sending the message; may be nil.

    Discussion

    Automatic link detection causes strings representing URLs typed in the view to be automatically made into links to those URLs.

    Availability

    Available in OS X v10.5 and later.

  • A Boolean that indicates whether the text view automatically supplies the destination of a link as a tooltip for text that has a link attribute.

    Declaration

    Swift

    var displaysLinkToolTips: Bool

    Objective-C

    @property BOOL displaysLinkToolTips

    Discussion

    YEStrue if link tooltips are automatically displayed; otherwise, NOfalse.

    The default value for this feature is YEStrue; clients who do not wish tooltips to be displayed automatically must explicitly disable it.

    Availability

    Available in OS X v10.5 and later.

  • A Boolean that controls whether the text views sharing the receiver’s layout manager use a ruler.

    Declaration

    Swift

    var usesRuler: Bool

    Objective-C

    @property BOOL usesRuler

    Discussion

    YEStrue to cause text views sharing the receiver's layout manager to respond to NSRulerView client messages and to paragraph-related menu actions, and update the ruler (when visible) as the selection changes with its paragraph and tab attributes, otherwise NOfalse.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean that controls whether the scroll view enclosing text views sharing the receiver’s layout manager displays the ruler.

    Declaration

    Swift

    var rulerVisible: Bool

    Objective-C

    @property(getter=isRulerVisible) BOOL rulerVisible

    Discussion

    YEStrue to show the ruler, NOfalse to hide the ruler. By default, the ruler is hidden.

    Availability

    Available in OS X v10.10 and later.

    See Also

    usesRuler
    toggleRuler: (NSText)

  • A Boolean that indicates whether this text view uses the inspector bar.

    Declaration

    Swift

    var usesInspectorBar: Bool

    Objective-C

    @property BOOL usesInspectorBar

    Discussion

    The inspector bar displays text formatting controls, much like those in iWork applications, which can be used in place of the formatting controls in the ruler accessory view.

    Availability

    Available in OS X v10.7 and later.

  • An array containing the ranges of characters selected in the receiver’s layout manager.

    Declaration

    Swift

    var selectedRanges: [NSValue]

    Objective-C

    @property(copy) NSArray <NSValue *> *selectedRanges

    Discussion

    The objects in the array are sorted, non-overlapping, non-contiguous, and (except for the case of a single range) have non-zero-length

    Availability

    Available in OS X v10.4 and later.

  • Sets the selection to the characters in an array of ranges.

    Declaration

    Swift

    func setSelectedRange(_ charRange: NSRange)

    Objective-C

    - (void)setSelectedRange:(NSRange)charRange

    Parameters

    charRange

    A non-nil, non-empty array of objects responding to the NSValue rangeValue method. The ranges in the ranges array must begin and end on glyph boundaries and not split base glyphs and their nonspacing marks.

    Availability

    Available in OS X v10.0 and later.

  • Sets the selection to a range of characters in response to user action.

    Declaration

    Swift

    func setSelectedRange(_ charRange: NSRange, affinity affinity: NSSelectionAffinity, stillSelecting stillSelectingFlag: Bool)

    Objective-C

    - (void)setSelectedRange:(NSRange)charRange affinity:(NSSelectionAffinity)affinity stillSelecting:(BOOL)flag

    Parameters

    charRange

    The range of characters to select. This range must begin and end on glyph boundaries and not split base glyphs and their nonspacing marks.

    affinity

    The selection affinity for the selection. See selectionAffinity for more information about how affinities work.

    flag

    YEStrue to behave appropriately for a continuing selection where the user is still dragging the mouse, NOfalse otherwise. If YEStrue, the receiver doesn’t send notifications or remove the marking from its marked text. If NOfalse, the receiver posts an NSTextViewDidChangeSelectionNotification to the default notification center and removes the marking from marked text if the new selection is greater than the marked region.

    Discussion

    This method resets the selection granularity to NSSelectByCharacter.

    Special Considerations

    In OS X version 10.4 and later, if there are multiple selections, this method acts on the first selected subrange.

    Availability

    Available in OS X v10.0 and later.

  • Sets the selection to the characters in an array of ranges in response to user action.

    Declaration

    Swift

    func setSelectedRanges(_ ranges: [NSValue], affinity affinity: NSSelectionAffinity, stillSelecting stillSelectingFlag: Bool)

    Objective-C

    - (void)setSelectedRanges:(NSArray<NSValue *> *)ranges affinity:(NSSelectionAffinity)affinity stillSelecting:(BOOL)stillSelectingFlag

    Parameters

    ranges

    A non-nil, non-empty array of objects responding to the NSValue rangeValue method. The ranges in the ranges array must begin and end on glyph boundaries and not split base glyphs and their nonspacing marks.

    affinity

    The selection affinity for the selection. See selectionAffinity for more information about how affinities work.

    stillSelectingFlag

    YEStrue to behave appropriately for a continuing selection where the user is still dragging the mouse, NOfalse otherwise. If YEStrue, the receiver doesn’t send notifications or remove the marking from its marked text. If NOfalse, the receiver posts an NSTextViewDidChangeSelectionNotification to the default notification center and removes the marking from marked text if the new selection is greater than the marked region.

    Discussion

    This method also resets the selection granularity to NSSelectByCharacter.

    Availability

    Available in OS X v10.4 and later.

  • The preferred direction of selection. (read-only)

    Declaration

    Swift

    var selectionAffinity: NSSelectionAffinity { get }

    Objective-C

    @property(readonly) NSSelectionAffinity selectionAffinity

    Discussion

    Selection affinity determines whether, for example, the insertion point appears after the last character on a line or before the first character on the following line in cases where text wraps across line boundaries.

    Availability

    Available in OS X v10.0 and later.

  • The selection granularity for subsequent extension of a selection.

    Declaration

    Swift

    var selectionGranularity: NSSelectionGranularity

    Objective-C

    @property NSSelectionGranularity selectionGranularity

    Discussion

    Selection granularity is used to determine how the selection is modified when the user Shift-clicks or drags the mouse after a double or triple click. For example, if the user selects a word by double-clicking, the selection granularity is set to NSSelectByWord. Subsequent Shift-clicks then extend the selection by words.

    Selection granularity is reset to NSSelectByCharacter whenever the selection is set. You should always set the selection granularity after setting the selection.

    Availability

    Available in OS X v10.0 and later.

    See Also

    selectedRanges

  • The color of the insertion point.

    Declaration

    Swift

    @NSCopying var insertionPointColor: NSColor

    Objective-C

    @property(copy) NSColor *insertionPointColor

    Availability

    Available in OS X v10.0 and later.

  • Updates the insertion point’s location and optionally restarts the blinking cursor timer.

    Declaration

    Swift

    func updateInsertionPointStateAndRestartTimer(_ restartFlag: Bool)

    Objective-C

    - (void)updateInsertionPointStateAndRestartTimer:(BOOL)flag

    Parameters

    flag

    YEStrue to restart the blinking cursor timer, NOfalse otherwise.

    Discussion

    This method is invoked automatically whenever the insertion point needs to be moved; you should never need to invoke it directly, but you can override it to modify insertion point behavior.

    Availability

    Available in OS X v10.0 and later.

  • The attributes used to indicate the selection.

    Declaration

    Swift

    var selectedTextAttributes: [String : AnyObject]

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *selectedTextAttributes

    Discussion

    Text color, background color, and underline are the only supported attributes for selected text.

    Availability

    Available in OS X v10.0 and later.

    See Also

    selectedRange (NSTextInput)

  • The attributes used to draw marked text.

    Declaration

    Swift

    var markedTextAttributes: [String : AnyObject]?

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *markedTextAttributes

    Discussion

    Text color, background color, and underline are the only supported attributes for marked text.

    Availability

    Available in OS X v10.0 and later.

    See Also

    markedRange (NSTextInput)

  • The attributes used to draw the onscreen presentation of link text.

    Declaration

    Swift

    var linkTextAttributes: [String : AnyObject]?

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *linkTextAttributes

    Discussion

    Link text attributes are applied as temporary attributes to any text with a link attribute. Candidates include those attributes that do not affect layout.

    Availability

    Available in OS X v10.3 and later.

  • Returns a character index appropriate for placing a zero-length selection for an insertion point associated with the mouse at the given point.

    Declaration

    Swift

    func characterIndexForInsertionAtPoint(_ point: NSPoint) -> Int

    Objective-C

    - (NSUInteger)characterIndexForInsertionAtPoint:(NSPoint)point

    Parameters

    point

    The point for which to return an index, in view coordinates.

    Return Value

    The character index for the insertion point.

    Discussion

    This method should be used for insertion points associated with mouse clicks, drag events, and so forth. For other purposes, it is better to use NSLayoutManager methods.

    The NSTextInput method characterIndexForPoint: is not suitable for this role; it is intended only for uses related to text input methods.

    Availability

    Available in OS X v10.5 and later.

  • Applies full justification to selected paragraphs (or all text, if the receiver is a plain text object).

    Declaration

    Swift

    func alignJustified(_ sender: AnyObject?)

    Objective-C

    - (void)alignJustified:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Availability

    Available in OS X v10.0 and later.

    See Also

    alignCenter: (NSText)
    alignLeft: (NSText)
    alignRight: (NSText)
    alignment (NSText)
    setAlignment: (NSText)

  • Changes the attributes of the current selection.

    Declaration

    Swift

    func changeAttributes(_ sender: AnyObject?)

    Objective-C

    - (void)changeAttributes:(id)sender

    Parameters

    sender

    The control that sent the message. Must respond to convertAttributes:.

    Discussion

    This method changes the attributes by invoking convertAttributes: on sender and applying the returned attributes to the appropriate text. See Font Handling in Cocoa Text Architecture Guide for more information on attribute conversion.

    Availability

    Available in OS X v10.3 and later.

  • Sets the color of the selected text.

    Declaration

    Swift

    func changeColor(_ sender: AnyObject?)

    Objective-C

    - (void)changeColor:(id)sender

    Parameters

    sender

    The control that sent the message. NSTextView’s implementation sends a color message to sender to get the new color.

    Availability

    Available in OS X v10.0 and later.

  • Sets the alignment of the paragraphs containing characters in the specified range.

    Declaration

    Swift

    func setAlignment(_ alignment: NSTextAlignment, range range: NSRange)

    Objective-C

    - (void)setAlignment:(NSTextAlignment)alignment range:(NSRange)aRange

    Parameters

    alignment

    The new alignment.

    aRange

    The range of characters whose paragraphs will have their alignment set.

    Discussion

    This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges:replacementStrings: or shouldChangeTextInRange:replacementString: to include this method in an undoable action.

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s typing attributes.

    Declaration

    Swift

    var typingAttributes: [String : AnyObject]

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *typingAttributes

    Discussion

    Typing attributes are reset automatically whenever the selection changes. However, if you add any user actions that change text attributes, the action should use this method to apply those attributes afterwards. User actions that change attributes should always set the typing attributes because there might not be a subsequent change in selection before the next typing.

    Availability

    Available in OS X v10.0 and later.

  • Set the receiver to use pair kerning data for the glyphs in its selection, or for all glyphs if the receiver is a plain text view.

    Declaration

    Swift

    func useStandardKerning(_ sender: AnyObject?)

    Objective-C

    - (void)useStandardKerning:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Discussion

    This data is taken from a font’s AFM file

    Availability

    Available in OS X v10.0 and later.

  • Lowers the baseline offset of selected text by 1 point, or of all text if the receiver is a plain text view.

    Declaration

    Swift

    func lowerBaseline(_ sender: AnyObject?)

    Objective-C

    - (void)lowerBaseline:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Discussion

    As such, this method defines a more primitive operation than subscripting.

    Availability

    Available in OS X v10.0 and later.

    See Also

    – raiseBaseline:
    subscript: (NSText)
    unscript: (NSText)

  • Raises the baseline offset of selected text by 1 point, or of all text if the receiver is a plain text view.

    Declaration

    Swift

    func raiseBaseline(_ sender: AnyObject?)

    Objective-C

    - (void)raiseBaseline:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Discussion

    As such, this method defines a more primitive operation than superscripting.

    Availability

    Available in OS X v10.0 and later.

    See Also

    – lowerBaseline:
    superscript: (NSText)
    unscript: (NSText)

  • Sets the receiver to use nominal glyph spacing for the glyphs in its selection, or for all glyphs if the receiver is a plain text view.

    Declaration

    Swift

    func turnOffKerning(_ sender: AnyObject?)

    Objective-C

    - (void)turnOffKerning:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Availability

    Available in OS X v10.0 and later.

  • Increases the space between glyphs in the receiver’s selection, or in all text if the receiver is a plain text view.

    Declaration

    Swift

    func loosenKerning(_ sender: AnyObject?)

    Objective-C

    - (void)loosenKerning:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Discussion

    Kerning values are determined by the point size of the fonts in the selection.

    Availability

    Available in OS X v10.0 and later.

  • Decreases the space between glyphs in the receiver’s selection, or for all glyphs if the receiver is a plain text view.

    Declaration

    Swift

    func tightenKerning(_ sender: AnyObject?)

    Objective-C

    - (void)tightenKerning:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Discussion

    Kerning values are determined by the point size of the fonts in the selection.

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver to use the standard ligatures available for the fonts and languages used when setting text, for the glyphs in the selection if the receiver is a rich text view, or for all glyphs if it’s a plain text view.

    Declaration

    Swift

    func useStandardLigatures(_ sender: AnyObject?)

    Objective-C

    - (void)useStandardLigatures:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver to use only required ligatures when setting text, for the glyphs in the selection if the receiver is a rich text view, or for all glyphs if it’s a plain text view.

    Declaration

    Swift

    func turnOffLigatures(_ sender: AnyObject?)

    Objective-C

    - (void)turnOffLigatures:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver to use all ligatures available for the fonts and languages used when setting text, for the glyphs in the selection if the receiver is a rich text view, or for all glyphs if it’s a plain text view.

    Declaration

    Swift

    func useAllLigatures(_ sender: AnyObject?)

    Objective-C

    - (void)useAllLigatures:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Availability

    Available in OS X v10.0 and later.

  • Toggles the NSCharacterShapeAttributeName attribute at the current selection.

    Declaration

    Swift

    func toggleTraditionalCharacterShape(_ sender: AnyObject?)

    Objective-C

    - (void)toggleTraditionalCharacterShape:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Discussion

    The NSCharacterShapeAttributeName constant is defined in NSAttributedString AppKit Additions Reference.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

  • Causes the text view to act as if the user clicked on some text with the given link as the value of a link attribute associated with the text.

    Declaration

    Swift

    func clickedOnLink(_ link: AnyObject, atIndex charIndex: Int)

    Objective-C

    - (void)clickedOnLink:(id)link atIndex:(NSUInteger)charIndex

    Parameters

    link

    The link that was clicked; the value of NSLinkAttributeName.

    charIndex

    The character index where the click occurred, indexed within the text storage.

    Discussion

    If, for instance, you have a special attachment cell that can follow links, you can use this method to ask the text view to follow a link once you decide it should. In addition, this method is invoked by the text view during mouse tracking if the user clicks a link.

    The charIndex parameter is a character index somewhere in the range of the link attribute. If the user actually physically clicked the link, then it should be the character that was originally clicked. In some cases a link may be opened indirectly or programmatically, in which case a character index somewhere in the range of the link attribute is supplied.

    This method sends the textView:clickedOnLink:atIndex: delegate message if the delegate implements it, so that the delegate can handle the click.

    Availability

    Available in OS X v10.0 and later.

    See Also

    textView:clickedOnLink:atIndex: (NSTextViewDelegate)

  • Inserts the contents of the pasteboard into the receiver’s text as plain text.

    Declaration

    Swift

    func pasteAsPlainText(_ sender: AnyObject?)

    Objective-C

    - (void)pasteAsPlainText:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Discussion

    This method behaves analogously to insertText:.

    Availability

    Available in OS X v10.0 and later.

  • This action method inserts the contents of the pasteboard into the receiver’s text as rich text, maintaining its attributes.

    Declaration

    Swift

    func pasteAsRichText(_ sender: AnyObject?)

    Objective-C

    - (void)pasteAsRichText:(id)sender

    Parameters

    sender

    The control that sent the message; may be nil.

    Discussion

    The text is inserted at the insertion point if there is one, otherwise replacing the selection.

    Availability

    Available in OS X v10.0 and later.

  • Informs the receiver that it should begin coalescing successive typing operations in a new undo grouping.

    Declaration

    Swift

    func breakUndoCoalescing()

    Objective-C

    - (void)breakUndoCoalescing

    Special Considerations

    This method should be invoked when saving the receiver’s contents to preserve proper tracking of unsaved changes and the document’s dirty state.

    Availability

    Available in OS X v10.4 and later.

  • A Boolean that indicates whether undo coalescing is in progress. (read-only)

    Declaration

    Swift

    var coalescingUndo: Bool { get }

    Objective-C

    @property(getter=isCoalescingUndo, readonly) BOOL coalescingUndo

    Discussion

    YEStrue if undo coalescing is in progress, otherwise NOfalse.

    Availability

    Available in OS X v10.6 and later.

  • Updates the Font panel to contain the font attributes of the selection.

    Declaration

    Swift

    func updateFontPanel()

    Objective-C

    - (void)updateFontPanel

    Discussion

    Does nothing if the receiver doesn’t use the Font panel. You should never need to invoke this method directly, but you can override it if needed to handle additional font attributes.

    Availability

    Available in OS X v10.0 and later.

    See Also

    usesFontPanel

  • Updates the ruler view in the receiver’s enclosing scroll view to reflect the selection’s paragraph and marker attributes.

    Declaration

    Swift

    func updateRuler()

    Objective-C

    - (void)updateRuler

    Discussion

    Does nothing if the ruler isn’t visible or if the receiver doesn’t use the ruler. You should never need to invoke this method directly, but you can override this method if needed to handle additional ruler attributes.

    Availability

    Available in OS X v10.0 and later.

    See Also

    usesRuler

  • The data types that the receiver accepts as the destination view of a dragging operation. (read-only)

    Declaration

    Swift

    var acceptableDragTypes: [String] { get }

    Objective-C

    @property(readonly, copy) NSArray <NSString *> *acceptableDragTypes

    Discussion

    These types are automatically registered as necessary by the text view. Subclasses should override this value as necessary to add their own types to those returned by NSTextView’s implementation. They must then also override the appropriate methods of the NSDraggingDestination protocol to support import of those types. See that protocol’s specification for more information.

    Availability

    Available in OS X v10.0 and later.

  • Updates the acceptable drag types of all text views associated with the receiver's layout manager.

    Declaration

    Swift

    func updateDragTypeRegistration()

    Objective-C

    - (void)updateDragTypeRegistration

    Discussion

    If the receiver is editable and is a rich text view, causes all text views associated with the receiver’s layout manager to register their acceptable drag types. If the text view isn’t editable or isn’t rich text, causes those text views to unregister their dragged types.

    Subclasses can override this method to change the conditions for registering and unregistering drag types, whether as a group or individually based on the current state of the text view. They should invoke this method when that state changes to perform the necessary update.

    Availability

    Available in OS X v10.0 and later.

  • Returns an adjusted selected range based on the selection granularity.

    Declaration

    Swift

    func selectionRangeForProposedRange(_ proposedCharRange: NSRange, granularity granularity: NSSelectionGranularity) -> NSRange

    Objective-C

    - (NSRange)selectionRangeForProposedRange:(NSRange)proposedSelRange granularity:(NSSelectionGranularity)granularity

    Parameters

    proposedSelRange

    The proposed selected range.

    granularity

    The selection granularity.

    Return Value

    The adjusted selected range, taking into account the selection granularity.

    Discussion

    This method is invoked repeatedly during mouse tracking to modify the range of the selection. Override this method to specialize selection behavior.

    Availability

    Available in OS X v10.0 and later.

  • The range of characters affected by an action method that changes character (not paragraph) attributes. (read-only)

    Declaration

    Swift

    var rangeForUserCharacterAttributeChange: NSRange { get }

    Objective-C

    @property(readonly) NSRange rangeForUserCharacterAttributeChange

    Discussion

    The range of characters affected by an action method that changes character (not paragraph) attributes, such as the NSText action method changeFont:. For rich text this range is typically the range of the selection. For plain text this range is the entire contents of the receiver. If the receiver isn’t editable or doesn’t use the Font panel, the range has a location of NSNotFound.

    Availability

    Available in OS X v10.0 and later.

  • An array containing the ranges of characters affected by an action method that changes character (not paragraph) attributes. (read-only)

    Declaration

    Swift

    var rangesForUserCharacterAttributeChange: [NSValue]? { get }

    Objective-C

    @property(readonly, copy) NSArray <NSValue *> *rangesForUserCharacterAttributeChange

    Discussion

    An array containing the ranges of characters affected by an action method that changes character (not paragraph) attributes, such as the NSText action method changeFont:. For rich text these ranges are typically the ranges of the selections. For plain text the range is the entire contents of the receiver.

    Availability

    Available in OS X v10.4 and later.

  • The range of characters affected by an action method that changes paragraph (not character) attributes. (read-only)

    Declaration

    Swift

    var rangeForUserParagraphAttributeChange: NSRange { get }

    Objective-C

    @property(readonly) NSRange rangeForUserParagraphAttributeChange

    Discussion

    The range of characters affected by an action method that changes paragraph (not character) attributes, such as the NSText action method alignLeft:. For rich text this range is typically calculated by extending the range of the selection to paragraph boundaries. For plain text this range is the entire contents of the receiver. If the receiver isn’t editable or doesn’t use the Font panel, the range has a location of NSNotFound.

    Availability

    Available in OS X v10.0 and later.

  • An array containing the ranges of characters affected by a method that changes paragraph (not character) attributes. (read-only)

    Declaration

    Swift

    var rangesForUserParagraphAttributeChange: [NSValue]? { get }

    Objective-C

    @property(readonly, copy) NSArray <NSValue *> *rangesForUserParagraphAttributeChange

    Discussion

    For rich text these ranges are typically calculated by extending the range of the selection to paragraph boundaries. For plain text the range is the entire contents of the receiver.

    Availability

    Available in OS X v10.4 and later.

  • The range of characters affected by a method that changes characters (as opposed to attributes). (read-only)

    Declaration

    Swift

    var rangeForUserTextChange: NSRange { get }

    Objective-C

    @property(readonly) NSRange rangeForUserTextChange

    Discussion

    If the receiver isn’t editable the range has a location of NSNotFound.

    Availability

    Available in OS X v10.0 and later.

  • An array containing the ranges of characters affected by a method that changes characters (as opposed to attributes). (read-only)

    Declaration

    Swift

    var rangesForUserTextChange: [NSValue]? { get }

    Objective-C

    @property(readonly, copy) NSArray <NSValue *> *rangesForUserTextChange

    Availability

    Available in OS X v10.4 and later.

  • Initiates a series of delegate messages (and general notifications) to determine whether modifications can be made to the characters and attributes of the receiver’s text.

    Declaration

    Swift

    func shouldChangeTextInRange(_ affectedCharRange: NSRange, replacementString replacementString: String?) -> Bool

    Objective-C

    - (BOOL)shouldChangeTextInRange:(NSRange)affectedCharRange replacementString:(NSString *)replacementString

    Parameters

    affectedCharRange

    The range of characters affected by the proposed change.

    replacementString

    The characters that will replace those in affectedCharRange. If only text attributes are being changed, replacementString is nil.

    Return Value

    YEStrue to allow the change, NOfalse to prohibit it.

    Discussion

    This method checks with the delegate as needed using textShouldBeginEditing: and textView:shouldChangeTextInRange:replacementString:.

    This method must be invoked at the start of any sequence of user-initiated editing changes. If your subclass of NSTextView implements

    that modify the text, make sure to invoke this method to determine whether the change should be made. If the change is allowed, complete the change by invoking the didChangeText method. If you can’t determine the affected range or replacement string before beginning changes, pass (NSNotFound, 0) and nil for these values.

    Special Considerations

    If you override this method, you must call super at the beginning of the override.

    If the receiver is not editable, this method automatically returns NOfalse. This result prevents instances in which a text view could be changed by user actions even though it had been set to be non-editable.

    In OS X version 10.4 and later, if there are multiple selections, this method acts on the first selected subrange.

    Availability

    Available in OS X v10.0 and later.

  • Initiates a series of delegate messages (and general notifications) to determine whether modifications can be made to the characters and attributes of the receiver’s text.

    Declaration

    Swift

    func shouldChangeTextInRanges(_ affectedRanges: [NSValue], replacementStrings replacementStrings: [String]?) -> Bool

    Objective-C

    - (BOOL)shouldChangeTextInRanges:(NSArray<NSValue *> *)affectedRanges replacementStrings:(NSArray<NSString *> *)replacementStrings

    Parameters

    affectedRanges

    An array of ranges to change.

    replacementStrings

    An array of strings containing the characters that replace those in affectedRanges, one for each range. If only text attributes are being changed, replacementStrings is nil.

    Return Value

    YEStrue to allow the change, NOfalse to prohibit it.

    Discussion

    This method checks with the delegate as needed using textShouldBeginEditing: and textView:shouldChangeTextInRanges:replacementStrings:.

    This method must be invoked at the start of any sequence of user-initiated editing changes. If your subclass of NSTextView implements

    that modify the text, make sure to invoke this method to determine whether the change should be made. If the change is allowed, complete the change by invoking the didChangeText method. If you can’t determine the affected range or replacement string before beginning changes, pass nil for these values.

    Special Considerations

    If you override this method, you must call super at the beginning of the override.

    If the receiver is not editable, this method automatically returns NOfalse. This result prevents instances in which a text view could be changed by user actions even though it had been set to be non-editable.

    Availability

    Available in OS X v10.4 and later.

    See Also

    editable

  • Sends out necessary notifications when a text change completes.

    Declaration

    Swift

    func didChangeText()

    Objective-C

    - (void)didChangeText

    Discussion

    Invoked automatically at the end of a series of changes, this method posts an NSTextDidChangeNotification to the default notification center, which also results in the delegate receiving an NSText delegate textDidChange: message.

    Subclasses implementing methods that change their text should invoke this method at the end of those methods. See Subclassing NSTextView for more information.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean that controls whether the receiver inserts or deletes space around selected words so as to preserve proper spacing and punctuation.

    Declaration

    Swift

    var smartInsertDeleteEnabled: Bool

    Objective-C

    @property BOOL smartInsertDeleteEnabled

    Discussion

    YEStrue if the receiver should insert or delete space around selected words so as to preserve proper spacing and punctuation, NOfalse if it should insert and delete exactly what’s selected.

    Availability

    Available in OS X v10.0 and later.

  • Returns an extended range that includes adjacent whitespace that should be deleted along with the proposed range in order to preserve proper spacing and punctuation.

    Declaration

    Swift

    func smartDeleteRangeForProposedRange(_ proposedCharRange: NSRange) -> NSRange

    Objective-C

    - (NSRange)smartDeleteRangeForProposedRange:(NSRange)proposedCharRange

    Parameters

    proposedCharRange

    The proposed character range for deleting.

    Return Value

    An extended range that includes adjacent whitespace that should be deleted along with the proposed range in order to preserve proper spacing and punctuation of the text surrounding the deletion.

    Discussion

    NSTextView uses this method as necessary; you can also use it in implementing your own methods that delete text, typically when the selection granularity is NSSelectByWord. To do so, invoke this method with the proposed range to delete, then actually delete the range returned. If placing text on the pasteboard, however, you should put only the characters from the proposed range onto the pasteboard.

    Availability

    Available in OS X v10.0 and later.

  • Returns any whitespace that needs to be added after the string to preserve proper spacing and punctuation when the string replaces the characters in the specified range.

    Declaration

    Swift

    func smartInsertAfterStringForString(_ pasteString: String, replacingRange charRangeToReplace: NSRange) -> String?

    Objective-C

    - (NSString *)smartInsertAfterStringForString:(NSString *)aString replacingRange:(NSRange)charRange

    Parameters

    aString

    The string that is replacing the characters in charRange.

    charRange

    The range of characters which aString is replacing.

    Return Value

    Any whitespace that needs to be added after aString to preserve proper spacing and punctuation when the characters in charRange are replaced by aString. If aString is nil or if smart insertion and deletion are disabled, this method returns nil.

    Discussion

    Don’t invoke this method directly. Instead, use smartInsertForString:replacingRange:beforeString:afterString:, which calls this method as part of its implementation.

    Availability

    Available in OS X v10.0 and later.

  • Returns any whitespace that needs to be added before the string to preserve proper spacing and punctuation when the string replaces the characters in the specified range.

    Declaration

    Swift

    func smartInsertBeforeStringForString(_ pasteString: String, replacingRange charRangeToReplace: NSRange) -> String?

    Objective-C

    - (NSString *)smartInsertBeforeStringForString:(NSString *)aString replacingRange:(NSRange)charRange

    Parameters

    aString

    The string that is replacing the characters in charRange.

    charRange

    The range of characters which aString is replacing.

    Return Value

    Any whitespace that needs to be added before aString to preserve proper spacing and punctuation when the characters in charRange are replaced by aString. If aString is nil or if smart insertion and deletion are disabled, this method returns nil.

    Discussion

    Don’t invoke this method directly. Instead, use smartInsertForString:replacingRange:beforeString:afterString:, which calls this method as part of its implementation.

    Availability

    Available in OS X v10.0 and later.

  • Determines whether whitespace needs to be added around the string to preserve proper spacing and punctuation when it replaces the characters in the specified range.

    Declaration

    Swift

    func smartInsertForString(_ pasteString: String, replacingRange charRangeToReplace: NSRange, beforeString beforeString: AutoreleasingUnsafeMutablePointer<NSString?>, afterString afterString: AutoreleasingUnsafeMutablePointer<NSString?>)

    Objective-C

    - (void)smartInsertForString:(NSString *)aString replacingRange:(NSRange)charRange beforeString:(NSString * _Nullable *)beforeString afterString:(NSString * _Nullable *)afterString

    Parameters

    aString

    The string that is replacing the characters in charRange.

    charRange

    The range of characters which aString is replacing.

    beforeString

    On return, a pointer to the string with the characters that should be added before aString; nil if there are no characters to add, if aString is nil, or if smart insertion and deletion are disabled.

    afterString

    On return, a pointer to the string with the characters that should be added after aString; nil if there are no characters to add, if aString is nil, or if smart insertion and deletion are disabled.

    Discussion

    As part of its implementation, this method calls smartInsertAfterStringForString:replacingRange: and smartInsertBeforeStringForString:replacingRange:. To change this method’s behavior, override those two methods instead of this one.

    NSTextView uses this method as necessary. You can also use it in implementing your own methods that insert text. To do so, invoke this method with the proper arguments, then insert beforeString, aString, and afterString in order over charRange.

    Availability

    Available in OS X v10.0 and later.

  • Changes the state of smart insert and delete from enabled to disabled and vice versa.

    Declaration

    Swift

    func toggleSmartInsertDelete(_ sender: AnyObject?)

    Objective-C

    - (void)toggleSmartInsertDelete:(id)sender

    Parameters

    sender

    The control sending the message; may be nil.

    Discussion

    Controls whether the receiver inserts or deletes space around selected words so as to preserve proper spacing and punctuation.

    Availability

    Available in OS X v10.5 and later.

  • Creates and displays a new instance of the the sharing service picker.

    Declaration

    Swift

    @IBAction func orderFrontSharingServicePicker(_ sender: AnyObject?)

    Objective-C

    - (IBAction)orderFrontSharingServicePicker:(id)sender

    Parameters

    sender

    The sender.

    Discussion

    Creates a new instance of NSSharingServicePicker based on the current selection & shows to the screen. The items passed to the NSSharingServicePicker initializer are determined using the delegate method textView:willShowSharingServicePicker:forItems:.

    When the current selection is 0 length, the whole document is passed to the method.

    Availability

    Available in OS X v10.8 and later.

  • Returns an appropriate drag image for the drag initiated by the specified event.

    Declaration

    Swift

    func dragImageForSelectionWithEvent(_ event: NSEvent, origin origin: NSPointPointer) -> NSImage?

    Objective-C

    - (NSImage *)dragImageForSelectionWithEvent:(NSEvent *)event origin:(NSPointPointer)origin

    Parameters

    event

    The event that initiated the drag session.

    origin

    On return, the lower-left point of the image in view coordinates.

    Return Value

    An appropriate drag image for the drag initiated by event. May be nil, in which case a default icon will be used.

    Discussion

    This method is used by dragSelectionWithEvent:offset:slideBack:. It can be called by others who need such an image, or can be overridden by subclasses to return a different image.

    Availability

    Available in OS X v10.0 and later.

  • Returns the type of drag operation that should be performed if the image were released now.

    Declaration

    Swift

    func dragOperationForDraggingInfo(_ dragInfo: NSDraggingInfo, type type: String) -> NSDragOperation

    Objective-C

    - (NSDragOperation)dragOperationForDraggingInfo:(id<NSDraggingInfo>)dragInfo type:(NSString *)type

    Parameters

    dragInfo

    The drag information.

    type

    The pasteboard type that will be read from the dragging pasteboard.

    Return Value

    The drag operation that should be performed if the image were released now.

    Discussion

    The returned value should be one of the following:

    Option

    Meaning

    NSDragOperationCopy

    The data represented by the image will be copied.

    NSDragOperationLink

    The data will be shared.

    NSDragOperationGeneric

    The operation will be defined by the destination.

    NSDragOperationPrivate

    The operation is negotiated privately between the source and the destination.

    If none of the operations is appropriate, this method should return NSDragOperationNone.

    This method is called repeatedly from draggingEntered: and draggingUpdated: as the user drags the image.

    Availability

    Available in OS X v10.0 and later.

    See Also

    draggingEntered: (NSDraggingDestination)
    draggingUpdated: (NSDraggingDestination)

  • Begins dragging the current selected text range.

    Declaration

    Swift

    func dragSelectionWithEvent(_ event: NSEvent, offset mouseOffset: NSSize, slideBack slideBack: Bool) -> Bool

    Objective-C

    - (BOOL)dragSelectionWithEvent:(NSEvent *)event offset:(NSSize)mouseOffset slideBack:(BOOL)slideBack

    Parameters

    event

    The event that initiated dragging the selection.

    mouseOffset

    The cursor’s current location relative to the mouse-down event.

    slideBack

    YEStrue if the image being dragged should slide back to its original position if the drag does not succeed, NOfalse otherwise.

    Return Value

    YEStrue if the drag can be successfully initiated, NOfalse otherwise.

    Discussion

    Primarily for subclasses, who can override it to intervene at the beginning of a drag.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean that indicates whether the receiver accepts the glyph info attribute.

    Declaration

    Swift

    var acceptsGlyphInfo: Bool

    Objective-C

    @property BOOL acceptsGlyphInfo

    Discussion

    YEStrue if the receiver accepts the NSGlyphInfoAttributeName attribute from text input sources such as input methods and the pasteboard, NOfalse otherwise.

    Availability

    Available in OS X v10.2 and later.

  • Speaks the selected text, or all text if no selection.

    Declaration

    Swift

    func startSpeaking(_ sender: AnyObject?)

    Objective-C

    - (void)startSpeaking:(id)sender

    Parameters

    sender

    The control sending the message; can be nil.

    Availability

    Available in OS X v10.1 and later.

  • Stops the speaking of text.

    Declaration

    Swift

    func stopSpeaking(_ sender: AnyObject?)

    Objective-C

    - (void)stopSpeaking:(id)sender

    Parameters

    sender

    The control sending the message; can be nil.

    Availability

    Available in OS X v10.1 and later.

  • A Boolean that controls whether the text views sharing the receiver’s layout manager use the Font panel and Font menu.

    Declaration

    Swift

    var usesFontPanel: Bool

    Objective-C

    @property BOOL usesFontPanel

    Discussion

    YEStrue to make the text views sharing the receiver’s layout manager respond to messages from the Font panel and from the Font menu, and update the Font panel with the selection font whenever it changes, NOfalse to disallow character attribute changes.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean that specifies whether the receiver allows for a find panel.

    Declaration

    Swift

    var usesFindPanel: Bool

    Objective-C

    @property BOOL usesFindPanel

    Discussion

    YEStrue to allow the use of a find panel, NOfalse otherwise.

    Availability

    Available in OS X v10.3 and later.

  • Performs a find panel action specified by the sender's tag.

    Declaration

    Swift

    func performFindPanelAction(_ sender: AnyObject?)

    Objective-C

    - (void)performFindPanelAction:(id)sender

    Parameters

    sender

    The control sending the message. This method sends the tag method to determine what operation to perform. The list of possible tags is provided in Constants.

    Discussion

    This is the generic action method for the find menu and find panel, and can be overridden to implement a custom find panel.

    Availability

    Available in OS X v10.3 and later.

  • Brings forward a panel allowing the user to manipulate links in the text view.

    Declaration

    Swift

    func orderFrontLinkPanel(_ sender: AnyObject?)

    Objective-C

    - (void)orderFrontLinkPanel:(id)sender

    Parameters

    sender

    The control sending the message. May be nil.

    Availability

    Available in OS X v10.4 and later.

  • Brings forward a panel allowing the user to manipulate text lists in the text view.

    Declaration

    Swift

    func orderFrontListPanel(_ sender: AnyObject?)

    Objective-C

    - (void)orderFrontListPanel:(id)sender

    Parameters

    sender

    The control sending the message. May be nil.

    Availability

    Available in OS X v10.4 and later.

  • Brings forward a panel allowing the user to manipulate text line heights, interline spacing, and paragraph spacing, in the text view.

    Declaration

    Swift

    func orderFrontSpacingPanel(_ sender: AnyObject?)

    Objective-C

    - (void)orderFrontSpacingPanel:(id)sender

    Parameters

    sender

    The control sending the message. May be nil.

    Availability

    Available in OS X v10.4 and later.

  • Brings forward a panel allowing the user to manipulate text tables in the text view.

    Declaration

    Swift

    func orderFrontTablePanel(_ sender: AnyObject?)

    Objective-C

    - (void)orderFrontTablePanel:(id)sender

    Parameters

    sender

    The control sending the message. May be nil.

    Availability

    Available in OS X v10.4 and later.

  • Brings forward a panel allowing the user to specify string substitutions in the text view.

    Declaration

    Swift

    func orderFrontSubstitutionsPanel(_ sender: AnyObject?)

    Objective-C

    - (void)orderFrontSubstitutionsPanel:(id)sender

    Parameters

    sender

    The control sending the message. May be nil.

    Availability

    Available in OS X v10.6 and later.

  • Invokes completion in a text view.

    Declaration

    Swift

    func complete(_ sender: AnyObject?)

    Objective-C

    - (void)complete:(id)sender

    Parameters

    sender

    The control sending the message. May be nil.

    Discussion

    By default invoked using the Escape key, this method provides users with a choice of completions for the word currently being typed. May be invoked programmatically if autocompletion is desired by a client of the text system. You can change the key invoking this method using the text system’s key bindings mechanism; see “Text System Defaults and Key Bindings" for an explanation of the procedure.

    The delegate may replace or modify the list of possible completions by implementing textView:completions:forPartialWordRange:indexOfSelectedItem:. Subclasses can control the list by overriding completionsForPartialWordRange:indexOfSelectedItem:.

    Availability

    Available in OS X v10.3 and later.

  • Returns an array of potential completions, in the order to be presented, representing possible word completions available from a partial word.

    Declaration

    Swift

    func completionsForPartialWordRange(_ charRange: NSRange, indexOfSelectedItem index: UnsafeMutablePointer<Int>) -> [String]?

    Objective-C

    - (NSArray<NSString *> *)completionsForPartialWordRange:(NSRange)charRange indexOfSelectedItem:(NSInteger *)index

    Parameters

    charRange

    The range of characters of the matched partial word to be completed.

    index

    On return, optionally set to the completion that should be initially selected. The default is 0, and –1 indicates no selection.

    Return Value

    An array of potential completions, in the order to be presented, representing possible word completions available from a partial word at charRange. Returning nil or a zero-length array suppresses completion.

    Discussion

    May be overridden by subclasses to modify or override the list of possible completions.

    This method should call the delegate method textView:completions:forPartialWordRange:indexOfSelectedItem: if the delegate implements such a method.

    Availability

    Available in OS X v10.3 and later.

  • Inserts the selected completion into the text at the appropriate location.

    Declaration

    Swift

    func insertCompletion(_ word: String, forPartialWordRange charRange: NSRange, movement movement: Int, isFinal flag: Bool)

    Objective-C

    - (void)insertCompletion:(NSString *)word forPartialWordRange:(NSRange)charRange movement:(NSInteger)movement isFinal:(BOOL)flag

    Parameters

    word

    The text to insert, including the matched partial word and its potential completion.

    charRange

    The range of characters of the matched partial word to be completed.

    movement

    The direction of movement. For possible values see the NSText Constants section. This value allows subclasses to distinguish between canceling completion and selection by arrow keys, by return, by tab, or by other means such as clicking.

    flag

    NOfalse while the user navigates through the potential text completions, YEStrue when a completion is definitively selected or cancelled and the original value is reinserted.

    Discussion

    This method has two effects, text substitution and changing of the selection:

    • It replaces the text between charRange.start and the current insertion point with word.

    • If flag is NOfalse it changes the selection to be the last n characters of word where n is equal to [word length] minus charRange.length, that is, the potential completion.

    • If flag is YEStrue it makes the selection empty and puts the insertion point just after word.

    Availability

    Available in OS X v10.3 and later.

  • The partial range from the most recent beginning of a word up to the insertion point. (read-only)

    Declaration

    Swift

    var rangeForUserCompletion: NSRange { get }

    Objective-C

    @property(readonly) NSRange rangeForUserCompletion

    Discussion

    This value is intended to be used for the range argument in the text completion methods such as completionsForPartialWordRange:indexOfSelectedItem:.

    Availability

    Available in OS X v10.3 and later.

  • - becomeFirstResponder Available in OS X v10.0 through OS X v10.4

    Informs the receiver that it’s becoming the first responder.

    Deprecation Statement

    Use the NSWindow method makeFirstResponder: to make a text view the first responder.

    Declaration

    Objective-C

    - (BOOL)becomeFirstResponder

    Return Value

    Returns YEStrue.

    Discussion

    If the previous first responder was not an NSTextView on the same NSLayoutManager as the receiving NSTextView, this method draws the selection and updates the insertion point if necessary.

    Use the NSWindow method makeFirstResponder:, not this method, to make a text view the first responder. Never invoke this method directly.

    Availability

    Available in OS X v10.0 through OS X v10.4.

    Not available to 64-bit applications.

  • - resignFirstResponder Available in OS X v10.0 through OS X v10.4

    Notifies the receiver that it’s been asked to relinquish its status as first responder.

    Deprecation Statement

    Use the NSWindow method makeFirstResponder: to make a text view the first responder.

    Declaration

    Objective-C

    - (BOOL)resignFirstResponder

    Return Value

    YEStrue if the text view will resign first responder, NOfalse otherwise.

    Discussion

    If the object that will become the new first responder is a text view attached to the same layout manager as the receiver, this method returns YEStrue with no further action. Otherwise, this method sends a textShouldEndEditing: message to its delegate (if any). If the delegate returns NOfalse, this method returns NOfalse. If the delegate returns YEStrue, this method hides the selection highlighting and posts an NSTextDidEndEditingNotification to the default notification center and then returns YEStrue.

    Use the NSWindow method makeFirstResponder:, not this method, to make a text view the first responder. Never invoke this method directly.

    Availability

    Available in OS X v10.0 through OS X v10.4.

    Not available to 64-bit applications.

  • Notifies the QuickLook panel that an update may be required.

    Declaration

    Swift

    func updateQuickLookPreviewPanel()

    Objective-C

    - (void)updateQuickLookPreviewPanel

    Discussion

    Notifies the QLPreviewPanel class for possible status changes with the data source or controller. Typically invoked in response to selection changes.

    Availability

    Available in OS X v10.7 and later.

  • An action message that toggles the visibility state of the Quick Look preview panel.

    Declaration

    Swift

    @IBAction func toggleQuickLookPreviewPanel(_ sender: AnyObject?)

    Objective-C

    - (IBAction)toggleQuickLookPreviewPanel:(id)sender

    Parameters

    sender

    The message sender.

    Discussion

    This action message toggles the visibility state of the Quick Look preview panel if the receiver is the current Quick Look controller.

    Availability

    Available in OS X v10.7 and later.

  • Returns an array of URLs for items that can be displayed by QuickLook in the specified ranges.

    Declaration

    Swift

    func quickLookPreviewableItemsInRanges(_ ranges: [NSValue]) -> [AnyObject]?

    Objective-C

    - (NSArray<id<QLPreviewItem>> *)quickLookPreviewableItemsInRanges:(NSArray<NSValue *> *)ranges

    Parameters

    ranges

    An array of ranges.

    Return Value

    Returns an array of document URLs for text attachment content, if available.

    Discussion

    Each preview item must conform to the QLPreviewItem protocol.

    Availability

    Available in OS X v10.7 and later.

  • These constants specify how much the text view extends the selection when the user drags the mouse. They’re used by selectionGranularity, and selectionRangeForProposedRange:granularity::

    Declaration

    Swift

    enum NSSelectionGranularity : UInt { case SelectByCharacter case SelectByWord case SelectByParagraph }

    Objective-C

    enum { NSSelectByCharacter = 0, NSSelectByWord = 1, NSSelectByParagraph = 2 }; typedef NSUInteger NSSelectionGranularity;

    Constants

    • SelectByCharacter

      NSSelectByCharacter

      Extends the selection character by character.

      Available in OS X v10.0 and later.

    • SelectByWord

      NSSelectByWord

      Extends the selection word by word.

      Available in OS X v10.0 and later.

    • SelectByParagraph

      NSSelectByParagraph

      Extends the selection paragraph by paragraph.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants specify the preferred direction of selection. They’re used by selectionAffinity and setSelectedRange:affinity:stillSelecting:.

    Declaration

    Swift

    enum NSSelectionAffinity : UInt { case Upstream case Downstream }

    Objective-C

    enum { NSSelectionAffinityUpstream = 0, NSSelectionAffinityDownstream = 1 }; typedef NSUInteger NSSelectionAffinity;

    Constants

    • Upstream

      NSSelectionAffinityUpstream

      The selection is moving toward the top of the document.

      Available in OS X v10.0 and later.

    • Downstream

      NSSelectionAffinityDownstream

      The selection is moving toward the bottom of the document.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants define the tags for performFindPanelAction:.

    These constants are deprecated in favor of the NSTextFinder equivalent constants defined in NSTextFinderAction constants.

    Declaration

    Swift

    enum NSFindPanelAction : UInt { case ShowFindPanel case Next case Previous case ReplaceAll case Replace case ReplaceAndFind case SetFindString case ReplaceAllInSelection case SelectAll case SelectAllInSelection }

    Objective-C

    enum { NSFindPanelActionShowFindPanel = 1, NSFindPanelActionNext = 2, NSFindPanelActionPrevious = 3, NSFindPanelActionReplaceAll = 4, NSFindPanelActionReplace = 5, NSFindPanelActionReplaceAndFind = 6, NSFindPanelActionSetFindString = 7, NSFindPanelActionReplaceAllInSelection = 8 }; typedef NSUInteger NSFindPanelAction;

    Constants

    • ShowFindPanel

      NSFindPanelActionShowFindPanel

      Displays the find panel.

      Available in OS X v10.3 and later.

    • Next

      NSFindPanelActionNext

      Finds the next instance of the queried text.

      Available in OS X v10.3 and later.

    • Previous

      NSFindPanelActionPrevious

      Finds the previous instance of the queried text.

      Available in OS X v10.3 and later.

    • ReplaceAll

      NSFindPanelActionReplaceAll

      Replaces all query instances within the text view.

      Available in OS X v10.3 and later.

    • Replace

      NSFindPanelActionReplace

      Replaces a single query instance within the text view.

      Available in OS X v10.3 and later.

    • ReplaceAndFind

      NSFindPanelActionReplaceAndFind

      Replaces a single query instance and finds the next.

      Available in OS X v10.3 and later.

    • SetFindString

      NSFindPanelActionSetFindString

      Sets the query string to the current selection.

      Available in OS X v10.3 and later.

    • ReplaceAllInSelection

      NSFindPanelActionReplaceAllInSelection

      Replaces all query instances within the selection.

      Available in OS X v10.3 and later.

    • SelectAll

      NSFindPanelActionSelectAll

      Selects all query instances in the text view.

      Available in OS X v10.4 and later.

    • SelectAllInSelection

      NSFindPanelActionSelectAllInSelection

      Selects all query instances within the selection.

      Available in OS X v10.4 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Locale identifiers represent the input sources available.

    Declaration

    Swift

    let NSAllRomanInputSourcesLocaleIdentifier: String

    Objective-C

    NSString *NSAllRomanInputSourcesLocaleIdentifier

    Constants

    • NSAllRomanInputSourcesLocaleIdentifier

      NSAllRomanInputSourcesLocaleIdentifier

      A meta-locale identifier representing the set of Roman input sources available. You can pass [NSArray arrayWithObject: NSAllRomanInputSourcesLocaleIdentifier] to the allowedInputSourceLocales property to restrict allowed input sources to Roman only.

      Available in OS X v10.5 and later.

  • In addition to communicating search strings via the find pasteboard, the standard Find panel for NSTextView also communicates search option metadata, including case sensitivity and substring matching options. This metadata is stored in a property list as the NSFindPanelSearchOptionsPboardType value on the global find pasteboard. As such, third party applications may store additional keys in this property list to communicate additional metadata as desired to support the various search options common to many third-party applications' Find panels.

    Declaration

    Swift

    let NSFindPanelSearchOptionsPboardType: String let NSFindPanelCaseInsensitiveSearch: String let NSFindPanelSubstringMatch: String

    Objective-C

    NSString *NSFindPanelSearchOptionsPboardType NSString *NSFindPanelCaseInsensitiveSearch NSString *NSFindPanelSubstringMatch

    Constants

    • NSFindPanelSearchOptionsPboardType

      NSFindPanelSearchOptionsPboardType

      Type for NSFindPanel metadata property list. Used with the NSPasteBoard method propertyListForType:.

      Available in OS X v10.5 and later.

    • NSFindPanelCaseInsensitiveSearch

      NSFindPanelCaseInsensitiveSearch

      Boolean value specifying whether the search is case-insensitive. YEStrue specifies a case-insensitive search; otherwise, NOfalse.

      Available in OS X v10.5 and later.

    • NSFindPanelSubstringMatch

      NSFindPanelSubstringMatch

      NSNumber object containing one of the values defined in NSFindPanelSubstringMatchType.

      Available in OS X v10.5 and later.

  • The type of substring matching used by the Find panel.

    Declaration

    Swift

    enum NSFindPanelSubstringMatchType : UInt { case Contains case StartsWith case FullWord case EndsWith }

    Objective-C

    enum { NSFindPanelSubstringMatchTypeContains = 0, NSFindPanelSubstringMatchTypeStartsWith = 1, NSFindPanelSubstringMatchTypeFullWord = 2, NSFindPanelSubstringMatchTypeEndsWith = 3 }; typedef NSUInteger NSFindPanelSubstringMatchType;

    Constants

    • Contains

      NSFindPanelSubstringMatchTypeContains

      Finds a word containing the search string.

      Available in OS X v10.5 and later.

    • StartsWith

      NSFindPanelSubstringMatchTypeStartsWith

      Finds a word starting with the search string.

      Available in OS X v10.5 and later.

    • FullWord

      NSFindPanelSubstringMatchTypeFullWord

      Finds a word exactly matching the search string.

      Available in OS X v10.5 and later.

    • EndsWith

      NSFindPanelSubstringMatchTypeEndsWith

      Finds a word ending with the search string.

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Posted when the selected range of characters changes.

    NSTextView posts this notification whenever setSelectedRange:affinity:stillSelecting: is invoked, either directly or through the many methods (mouseDown:, selectAll:, and so on) that invoke it indirectly. When the user is selecting text, this notification is posted only once, at the end of the selection operation. The text view's delegate receives a textViewDidChangeSelection: message when this notification is posted.

    The notification object is the notifying text view. The userInfo dictionary contains the following information:

    Key

    Value

    @"NSOldSelectedCharacterRange"

    An NSValue object containing an NSRange structure with the originally selected range.

    Declaration

    Swift

    let NSTextViewDidChangeSelectionNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Posted when a new text view is established as the text view that sends notifications.

    This notification allows observers to reregister themselves for the new text view. Methods such as removeTextContainerAtIndex:, textContainerChangedTextView:, and insertTextContainer:atIndex: cause this notification to be posted.

    The notification object is the old notifying text view, or nil. The userInfo dictionary contains the following information:

    Key

    Value

    @"NSOldNotifyingTextView"

    The old NSTextView, if one exists, otherwise nil.

    @"NSNewNotifyingTextView"

    The new NSTextView, if one exists, otherwise nil.

    There’s no delegate method associated with this notification. The text-handling system ensures that when a new text view replaces an old one as the notifying text view, the existing delegate becomes the delegate of the new text view, and the delegate is registered to receive text view notifications from the new notifying text view. All other observers are responsible for registering themselves on receiving this notification.

    Declaration

    Swift

    let NSTextViewWillChangeNotifyingTextViewNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Posted when there is a change in the typing attributes within a text view. This notification is posted, via the textViewDidChangeTypingAttributes: delegate method, whether or not text has changed as a result of the attribute change.

    Declaration

    Swift

    let NSTextViewDidChangeTypingAttributesNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.