NSTextViewDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Declared in
NSTextView.h
Companion guides
Related sample code

Overview

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

Tasks

Accessing Text System Objects

Controlling Display

Supporting Quick Look

Managing the Selection

Managing the Pasteboard

Setting Text Attributes

Clicking and Pasting

Working With the Spelling Checker

Dragging

Text Completion

Control Sharing Service Picker

Performing Commands

Contextual Menu Management

Deprecated Methods

Instance Methods

textView:clickedOnCell:inRect:

Sent when the user clicks a cell. (Deprecated. Use textView:clickedOnCell:inRect:atIndex: instead.)

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

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:clickedOnCell:inRect:atIndex:

Sent when the user clicks a cell.

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

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:clickedOnLink:

Sent after the user clicks on a link. (Deprecated. Use textView:clickedOnLink:atIndex: instead.)

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

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:clickedOnLink:atIndex:

Sent after the user clicks a link.

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

YES if the click was handled; otherwise, NO 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.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSTextView.h

textView:completions:forPartialWordRange:indexOfSelectedItem:

Returns the actual completions for a partial word.

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

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:didCheckTextInRange:types:options:results:orthography:wordCount:

Invoked to allow the delegate to modify the text checking results after checking has occurred.

- (NSArray *)textView:(NSTextView *)view didCheckTextInRange:(NSRange)range types:(NSTextCheckingTypes)checkingTypes options:(NSDictionary *)options results:(NSArray *)results orthography:(NSOrthography *)orthography wordCount:(NSInteger)wordCount
Parameters
view

The text view sending the message.

range

The range that was checked.

checkingTypes

The type of checking that was performed. The possible constants are listed in NSTextCheckingTypes and can be combined using the C bit-wise OR operator to perform multiple checks at the same time.

options

A dictionary of values used during the checking process to perform. See Spell Checking Option Dictionary Keys for the supported values.

results

An array of NSTextCheckingResult instances.

orthography

The orthography of the text.

wordCount

The number of words checked.

Return Value

An array of NSTextCheckingResult instances. You can return the results array as is, or an altered array of NSTextCheckingResult objects.

Discussion

Invoked by handleTextCheckingResults:forRange:types:options:orthography:wordCount:, this method allows observation of text checking, or modification of the results

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextView.h

textView:doCommandBySelector:

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

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

YES indicates that the delegate handled the command and the text view will not attempt to perform it; NO 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.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:doubleClickedOnCell:inRect:

Sent when the user double-clicks a cell. (Deprecated. Use textView:doubleClickedOnCell:inRect:atIndex: instead.)

- (void)textView:(NSTextView *)aTextView doubleClickedOnCell:(id < NSTextAttachmentCell >)attachmentCell 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.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:doubleClickedOnCell:inRect:atIndex:

Sent when the user double-clicks a cell.

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

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:draggedCell:inRect:event:

Sent when the user attempts to drag a cell. (Deprecated. Use textView:draggedCell:inRect:event:atIndex: instead.)

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

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:draggedCell:inRect:event:atIndex:

Sent when the user attempts to drag a cell.

- (void)textView:(NSTextView *)aTextView draggedCell:(id < NSTextAttachmentCell >)cell inRect:(NSRect)rect event:(NSEvent *)event atIndex:(NSUInteger)charIndex
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.

charIndex

The character position where the mouse button was clicked.

Discussion

The delegate can use this message as its cue to initiate a dragging operation.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:menu:forEvent:atIndex:

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

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

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:shouldChangeTextInRange:replacementString:

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

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

YES to allow the replacement, or NO 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.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:shouldChangeTextInRanges:replacementStrings:

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

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

YES to allow the replacement, or NO to reject the change.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:shouldChangeTypingAttributes:toAttributes:

Sent when the typing attributes are changed.

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

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:shouldSetSpellingState:range:

Sent when the spelling state is changed.

- (NSInteger)textView:(NSTextView *)textView shouldSetSpellingState:(NSInteger)value range:(NSRange)affectedCharRange
Parameters
textView

The text view sending the message.

value

The proposed spelling state value to set. Possible values, for the temporary attribute on the layout manager using the key NSSpellingStateAttributeName, are:

affectedCharRange

The character range over which to set the given spelling state.

Return Value

The actual spelling state to set.

Discussion

Delegate only. Allows delegate to control the setting of spelling and grammar indicators.

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSTextView.h

textView:URLForContentsOfTextAttachment:atIndex:

Returns a URL representing the document contents for a text attachment. (required)

- (NSURL *)textView:(NSTextView *)textView URLForContentsOfTextAttachment:(NSTextAttachment *)textAttachment atIndex:(NSUInteger)charIndex
Parameters
textView

The text view sending the message.

textAttachment

The text attachment object containing an NSFileWrapper object that holds the contents of the attached file.

charIndex

The character index of the text attachment.

Return Value

The absolute URL for the document contents represented by textAttachment.

Discussion

The returned NSURL object is used by the text view to provide default behaviors involving text attachments such as Quick Look and double-clicking. For example, the NSTextView method quickLookPreviewableItemsInRanges: uses this method for mapping text attachments to their corresponding document URLs, and NSTextView invokes the NSWorkspace method openURL: with the URL returned from this method when the delegate has no textView:doubleClickedOnCell:inRect:atIndex: implementation.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextView.h

textView:willChangeSelectionFromCharacterRange:toCharacterRange:

Returns the actual range to select.

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

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.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:willChangeSelectionFromCharacterRanges:toCharacterRanges:

Returns the actual character ranges to select.

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

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.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:willCheckTextInRange:options:types:

Invoked to allow the delegate to modify the text checking process before it occurs.

- (NSDictionary *)textView:(NSTextView *)view willCheckTextInRange:(NSRange)range options:(NSDictionary *)options types:(NSTextCheckingTypes *)checkingTypes
Parameters
view

The text view sending the message.

range

The range to be checked.

options

A dictionary of values used during the checking process to perform. See Spell Checking Option Dictionary Keys for the supported values.

checkingTypes

The type of checking to be performed, passed by-reference. The possible constants are listed in NSTextCheckingTypes and can be combined using the C bit-wise OR operator to perform multiple checks at the same time.

You can change this parameter to alter the types of checking to be performed.

Return Value

A dictionary containing an alternative to the options dictionary.

Discussion

Invoked by checkTextInRange:types:options:, this method allows control over text checking optionss (via the return value) or types (by modifying the flags pointed to by the inout parameter checkingTypes)

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextView.h

textView:willDisplayToolTip:forCharacterAtIndex:

Returns the actual tooltip to display.

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

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:willShowSharingServicePicker:forItems:

Returns a sharing service picker for the current selection.

- (NSSharingServicePicker *)textView:(NSTextView *)textView willShowSharingServicePicker:(NSSharingServicePicker *)servicePicker forItems:(NSArray *)items
Parameters
textView

The text view.

servicePicker

The service picker.

items

The ranges of the items to share.

Return Value

An NSSharingServicePicker instance. The original sharing picker or a new sharing picker instance can be returned.

Discussion

Returns a sharing service picker created for items right before shown to the screen when the orderFrontSharingServicePicker: method.

The delegate is specified as the delegate for the NSSharingServicePicker instance.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSTextView.h

textView:writablePasteboardTypesForCell:atIndex:

Returns the writable pasteboard types for a given cell.

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

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textView:writeCell:atIndex:toPasteboard:type:

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

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

YES if the write succeeded, NO otherwise.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textViewDidChangeSelection:

Sent when the selection changes in the text view.

- (void)textViewDidChangeSelection:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSTextViewDidChangeSelectionNotification.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

textViewDidChangeTypingAttributes:

Sent when a text view’s typing attributes change.

- (void)textViewDidChangeTypingAttributes:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSTextViewDidChangeTypingAttributesNotification.

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h

undoManagerForTextView:

Returns the undo manager for the specified text view.

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

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTextView.h