Mac Developer Library

Developer

AppKit Framework Reference NSTextViewDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSTextViewDelegate

The NSTextViewDelegate protocol defines the optional methods implemented by delegates of NSTextView objects.

Inheritance


Not Applicable

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.6 and later.
  • Returns the undo manager for the specified text view.

    Declaration

    Swift

    optional func undoManagerForTextView(_ aTextView: NSTextView) -> NSUndoManager?

    Objective-C

    - (NSUndoManager *)undoManagerForTextView:(NSTextView *)aTextView

    Parameters

    aTextView

    The text view whose undo manager should be returned.

    Return Value

    The undo manager for aTextView.

    Discussion

    This method provides the flexibility to return a custom undo manager for the text view. Although NSTextView implements undo and redo for changes to text, applications may need a custom undo manager to handle interactions between changes to text and changes to other items in the application.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Returns the actual tooltip to display.

    Declaration

    Swift

    optional func textView(_ textView: NSTextView, willDisplayToolTip tooltip: String, forCharacterAtIndex characterIndex: Int) -> String?

    Objective-C

    - (NSString *)textView:(NSTextView *)textView willDisplayToolTip:(NSString *)tooltip forCharacterAtIndex:(NSUInteger)characterIndex

    Parameters

    textView

    The text view sending the message.

    tooltip

    The proposed tooltip to display.

    characterIndex

    The location in textView.

    Return Value

    The actual tooltip to display, or nil to suppress display of the tooltip.

    Discussion

    The tooltip string is the value of the NSToolTipAttributeName attribute at characterIndex.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Returns the actual range to select.

    Declaration

    Swift

    optional func textView(_ aTextView: NSTextView, willChangeSelectionFromCharacterRange oldSelectedCharRange: NSRange, toCharacterRange newSelectedCharRange: NSRange) -> NSRange

    Objective-C

    - (NSRange)textView:(NSTextView *)aTextView willChangeSelectionFromCharacterRange:(NSRange)oldSelectedCharRange toCharacterRange:(NSRange)newSelectedCharRange

    Parameters

    aTextView

    The text view sending the message. This is the first text view in a series shared by a layout manager, not necessarily the text view displaying the selected text.

    oldSelectedCharRange

    The original range of the selection.

    newSelectedCharRange

    The proposed character range for the new selection.

    Return Value

    The actual character range for the new selection.

    Discussion

    This method is invoked before a text view finishes changing the selection—that is, when the last argument to a setSelectedRange:affinity:stillSelecting: message is NOfalse.

    Non-selectable text views do not process any mouse events. If for some reason it is necessary to disallow user selection change in a text view that handles mouse events, this can be achieved by making the text view selectable but implementing this delegate method to disallow selection changes.

    Special Considerations

    In OS X version 10.4 and later, if a delegate implements this delegate method and not its multiple-selection replacement, textView:willChangeSelectionFromCharacterRanges:toCharacterRanges:, then multiple selection is effectively disallowed; attempts to set the selected ranges call the old delegate method with the first subrange, and afterwards only a single selected range is set.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Returns the actual character ranges to select.

    Declaration

    Swift

    optional func textView(_ aTextView: NSTextView, willChangeSelectionFromCharacterRanges oldSelectedCharRanges: [AnyObject], toCharacterRanges newSelectedCharRanges: [AnyObject]) -> [AnyObject]

    Objective-C

    - (NSArray *)textView:(NSTextView *)aTextView willChangeSelectionFromCharacterRanges:(NSArray *)oldSelectedCharRanges toCharacterRanges:(NSArray *)newSelectedCharRanges

    Parameters

    aTextView

    The text view sending the message. This is the first text view in a series shared by a layout manager, not necessarily the text view displaying the selected text.

    oldSelectedCharRanges

    An array containing the original ranges of the selection. This must be a non-nil, non-empty array of objects responding to the NSValue method rangeValue, and in addition its elements must be sorted, non-overlapping, non-contiguous, and (except for the case of a single range) have non-zero-length.

    newSelectedCharRanges

    An array containing the proposed character ranges for the new selection. This must be a non-nil, non-empty array of objects responding to the NSValue method rangeValue, and in addition its elements must be sorted, non-overlapping, non-contiguous, and (except for the case of a single range) have non-zero-length.

    Return Value

    An array containing the actual character ranges for the new selection.

    Discussion

    Invoked before an NSTextView object finishes changing the selection—that is, when the last argument to a setSelectedRange:affinity:stillSelecting: or setSelectedRanges:affinity:stillSelecting: message is NOfalse.

    Non-selectable text views do not process any mouse events. If for some reason it is necessary to disallow user selection change in a text view that handles mouse events, this can be achieved by making the text view selectable but implementing this delegate method to disallow selection changes.

    If a delegate implements both this method and textView:willChangeSelectionFromCharacterRange:toCharacterRange:, then the latter is ignored.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent when the selection changes in the text view.

    Declaration

    Swift

    optional func textViewDidChangeSelection(_ aNotification: NSNotification)

    Objective-C

    - (void)textViewDidChangeSelection:(NSNotification *)aNotification

    Parameters

    aNotification

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Returns the writable pasteboard types for a given cell.

    Declaration

    Swift

    optional func textView(_ aTextView: NSTextView, writablePasteboardTypesForCell cell: NSTextAttachmentCellProtocol, atIndex charIndex: Int) -> [AnyObject]

    Objective-C

    - (NSArray *)textView:(NSTextView *)aTextView writablePasteboardTypesForCell:(id<NSTextAttachmentCell>)cell atIndex:(NSUInteger)charIndex

    Parameters

    aTextView

    The text view sending the message.

    cell

    The cell in question.

    charIndex

    The character index in the text view that was clicked.

    Return Value

    An array of types that can be written to the pasteboard for cell.

    Discussion

    This method is invoked after the user clicks cell at the specified charIndex location in aTextView. If the textView:draggedCell:inRect:event:atIndex: is not used, this method and textView:writeCell:atIndex:toPasteboard:type: allow aTextView to take care of attachment dragging and pasting, with the delegate responsible only for writing the attachment to the pasteboard.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Returns whether data of the specified type for the given cell could be written to the specified pasteboard.

    Declaration

    Swift

    optional func textView(_ aTextView: NSTextView, writeCell cell: NSTextAttachmentCellProtocol, atIndex charIndex: Int, toPasteboard pboard: NSPasteboard, type type: String) -> Bool

    Objective-C

    - (BOOL)textView:(NSTextView *)aTextView writeCell:(id<NSTextAttachmentCell>)cell atIndex:(NSUInteger)charIndex toPasteboard:(NSPasteboard *)pboard type:(NSString *)type

    Parameters

    aTextView

    The text view sending the message.

    cell

    The cell whose contents should be written to the pasteboard.

    charIndex

    The index at which the cell was accessed.

    pboard

    The pasteboard to which the cell's contents should be written.

    type

    The type of data that should be written.

    Return Value

    YEStrue if the write succeeded, NOfalse otherwise.

    Discussion

    The receiver should attempt to write the cell to pboard with the given type, and return success or failure.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent when a text view needs to determine if text in a specified range should be changed.

    Declaration

    Swift

    optional func textView(_ aTextView: NSTextView, shouldChangeTextInRange affectedCharRange: NSRange, replacementString replacementString: String) -> Bool

    Objective-C

    - (BOOL)textView:(NSTextView *)aTextView shouldChangeTextInRange:(NSRange)affectedCharRange replacementString:(NSString *)replacementString

    Parameters

    aTextView

    The text view sending the message. This is the first text view in a series shared by a layout manager, not necessarily the text view displaying the selected text.

    affectedCharRange

    The range of characters to be replaced.

    replacementString

    The characters that will replace the characters in affectedCharRange; nil if only text attributes are being changed.

    Return Value

    YEStrue to allow the replacement, or NOfalse to reject the change.

    Discussion

    If a delegate implements this method and not its multiple-selection replacement, textView:shouldChangeTextInRanges:replacementStrings:, it is called with an appropriate range and string. If a delegate implements the new method, then this one is ignored.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent when a text view needs to determine if text in an array of specified ranges should be changed.

    Declaration

    Swift

    optional func textView(_ textView: NSTextView, shouldChangeTextInRanges affectedRanges: [AnyObject], replacementStrings replacementStrings: [AnyObject]?) -> Bool

    Objective-C

    - (BOOL)textView:(NSTextView *)textView shouldChangeTextInRanges:(NSArray *)affectedRanges replacementStrings:(NSArray *)replacementStrings

    Parameters

    textView

    The text view sending the message. This is the first text view in a series shared by a layout manager, not necessarily the text view displaying the selected text.

    affectedRanges

    The array of ranges of characters to be replaced. This array must be a non-nil, non-empty array of objects responding to the NSValue rangeValue method, and in addition its elements must be sorted, non-overlapping, non-contiguous, and (except for the case of a single range) have non-zero-length.

    replacementStrings

    The array of strings that will replace the characters in affectedRanges, one string for each range; nil if only text attributes are being changed.

    Return Value

    YEStrue to allow the replacement, or NOfalse to reject the change.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent when the typing attributes are changed.

    Declaration

    Swift

    optional func textView(_ textView: NSTextView, shouldChangeTypingAttributes oldTypingAttributes: [NSObject : AnyObject], toAttributes newTypingAttributes: [NSObject : AnyObject]) -> [NSObject : AnyObject]

    Objective-C

    - (NSDictionary *)textView:(NSTextView *)textView shouldChangeTypingAttributes:(NSDictionary *)oldTypingAttributes toAttributes:(NSDictionary *)newTypingAttributes

    Parameters

    textView

    The text view sending the message.

    oldTypingAttributes

    The old typing attributes.

    newTypingAttributes

    The proposed typing attributes.

    Return Value

    The actual new typing attributes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent when a text view’s typing attributes change.

    Declaration

    Swift

    optional func textViewDidChangeTypingAttributes(_ aNotification: NSNotification)

    Objective-C

    - (void)textViewDidChangeTypingAttributes:(NSNotification *)aNotification

    Parameters

    aNotification

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent when the user clicks a cell.

    Declaration

    Swift

    optional func textView(_ aTextView: NSTextView, clickedOnCell cell: NSTextAttachmentCellProtocol, inRect cellFrame: NSRect, atIndex charIndex: Int)

    Objective-C

    - (void)textView:(NSTextView *)aTextView clickedOnCell:(id<NSTextAttachmentCell>)cell inRect:(NSRect)cellFrame atIndex:(NSUInteger)charIndex

    Parameters

    aTextView

    The text view sending the message.

    cell

    The cell clicked by the user.

    cellFrame

    The frame of the clicked cell.

    charIndex

    The character index of the clicked cell.

    Discussion

    The delegate can use this message as its cue to perform an action or select the attachment cell’s character. aTextView is the first text view in a series shared by a layout manager, not necessarily the one that draws cell.

    The delegate may subsequently receive a textView:doubleClickedOnCell:inRect:atIndex: message if the user continues to perform a double click.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent when the user double-clicks a cell.

    Declaration

    Swift

    optional func textView(_ aTextView: NSTextView, doubleClickedOnCell cell: NSTextAttachmentCellProtocol, inRect cellFrame: NSRect, atIndex charIndex: Int)

    Objective-C

    - (void)textView:(NSTextView *)aTextView doubleClickedOnCell:(id<NSTextAttachmentCell>)cell inRect:(NSRect)cellFrame atIndex:(NSUInteger)charIndex

    Parameters

    aTextView

    The text view sending the message.

    cell

    The cell double-clicked by the user.

    cellFrame

    The frame of the double-clicked cell.

    charIndex

    The character index of the double-clicked cell.

    Discussion

    The delegate can use this message as its cue to perform an action, such as opening the file represented by the attachment. aTextView is the first text view in a series shared by a layout manager, not necessarily the one that draws cell.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent after the user clicks a link.

    Declaration

    Swift

    optional func textView(_ aTextView: NSTextView, clickedOnLink link: AnyObject, atIndex charIndex: Int) -> Bool

    Objective-C

    - (BOOL)textView:(NSTextView *)aTextView clickedOnLink:(id)link atIndex:(NSUInteger)charIndex

    Parameters

    aTextView

    The text view sending the message.

    link

    The link that was clicked; the value of NSLinkAttributeName.

    charIndex

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

    Return Value

    YEStrue if the click was handled; otherwise, NOfalse to allow the next responder to handle it.

    Discussion

    The delegate can use this method to handle the click on the link. It is invoked by clickedOnLink:atIndex:.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

    See Also

    clickedOnLink:atIndex: (NSTextView)

  • Returns the actual completions for a partial word.

    Declaration

    Swift

    optional func textView(_ textView: NSTextView, completions words: [AnyObject], forPartialWordRange charRange: NSRange, indexOfSelectedItem index: UnsafeMutablePointer<Int>) -> [AnyObject]

    Objective-C

    - (NSArray *)textView:(NSTextView *)textView completions:(NSArray *)words forPartialWordRange:(NSRange)charRange indexOfSelectedItem:(NSInteger *)index

    Parameters

    textView

    The text view sending the message.

    words

    The proposed array of completions.

    charRange

    The range of characters to be completed.

    index

    On return, the index of the initially selected completion. The default is 0, and –1 indicates no selection.

    Return Value

    The actual array of completions that will be presented for the partial word at the given range. Returning nil or a zero-length array suppresses completion.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent to allow the delegate to perform the command for the text view.

    Declaration

    Swift

    optional func textView(_ aTextView: NSTextView, doCommandBySelector aSelector: Selector) -> Bool

    Objective-C

    - (BOOL)textView:(NSTextView *)aTextView doCommandBySelector:(SEL)aSelector

    Parameters

    aTextView

    The text view sending the message. This is the first text view in a series shared by a layout manager.

    aSelector

    The selector.

    Return Value

    YEStrue indicates that the delegate handled the command and the text view will not attempt to perform it; NOfalse indicates that the delegate did not handle the command the text view will attempt to perform it.

    Discussion

    This method is invoked by NSTextView's doCommandBySelector: method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Allows delegate to control the context menu returned by the text view.

    Declaration

    Swift

    optional func textView(_ view: NSTextView, menu menu: NSMenu, forEvent event: NSEvent, atIndex charIndex: Int) -> NSMenu?

    Objective-C

    - (NSMenu *)textView:(NSTextView *)view menu:(NSMenu *)menu forEvent:(NSEvent *)event atIndex:(NSUInteger)charIndex

    Parameters

    view

    The text view sending the message.

    menu

    The proposed contextual menu.

    event

    The mouse-down event that initiated the contextual menu’s display.

    charIndex

    The character position where the mouse button was clicked.

    Return Value

    A menu to use as the contextual menu. You can return menu unaltered, or you can return a customized menu.

    Discussion

    This method allows the delegate to control the context menu returned by menuForEvent:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent after the user clicks on a link.

    Deprecation Statement

    Use textView:clickedOnLink:atIndex: instead.

    Declaration

    Objective-C

    - (BOOL)textView:(NSTextView *)aTextView clickedOnLink:(id)link

    Parameters

    aTextView

    The text view sending the message.

    link

    The link that was clicked.

    Discussion

    This message is only sent if textView:clickedOnLink:atIndex: is not implemented.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent when the user attempts to drag a cell.

    Deprecation Statement

    Use textView:draggedCell:inRect:event:atIndex: instead.

    Declaration

    Objective-C

    - (void)textView:(NSTextView *)aTextView draggedCell:(id<NSTextAttachmentCell>)cell inRect:(NSRect)aRect event:(NSEvent *)theEvent

    Parameters

    aTextView

    The text view sending the message.

    cell

    The cell being dragged.

    aRect

    The rectangle from which the cell was dragged.

    theEvent

    The mouse-down event that preceded the mouse-dragged event.

    Discussion

    This method has been deprecated in favor of textView:draggedCell:inRect:event:atIndex:.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent when the user clicks a cell.

    Deprecation Statement

    Use textView:clickedOnCell:inRect:atIndex: instead.

    Declaration

    Objective-C

    - (void)textView:(NSTextView *)aTextView clickedOnCell:(id<NSTextAttachmentCell>)attachmentCell inRect:(NSRect)cellFrame

    Parameters

    aTextView

    The text view sending the message.

    attachmentCell

    The cell clicked by the user.

    cellFrame

    The frame of the clicked cell.

    Discussion

    This message is only sent if textView:clickedOnCell:inRect:atIndex: is not implemented. Implement this method in order to track the mouse after a mouse click on a cell.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sent when the user double-clicks a cell.

    Deprecation Statement

    Use textView:doubleClickedOnCell:inRect:atIndex: instead.

    Declaration

    Objective-C

    - (void)textView:(NSTextView *)aTextView doubleClickedOnCell:(id<NSTextAttachmentCell>)cell inRect:(NSRect)cellFrame

    Parameters

    aTextView

    The text view sending the message.

    cell

    The cell double-clicked by the user.

    cellFrame

    The frame of the double-clicked cell.

    Discussion

    This message is only sent if textView:doubleClickedOnCell:inRect:atIndex: is not implemented. Implement this method in order to track the mouse after a mouse double-click on a cell.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Available as part of an informal protocol prior to OS X v10.6.