Class

NSResponder

An abstract class that forms the basis of event and command processing in AppKit.

Overview

The core classes—NSApplication, NSWindow, and NSView—inherit from NSResponder, as must any class that handles events. The responder model is built around three components: event messages, action messages, and the responder chain.

NSResponder also plays an important role in the presentation of error information. The default implementations of the presentError(_:) and presentError(_:modalFor:delegate:didPresent:contextInfo:) methods send willPresentError(_:) to self, thereby giving subclasses the opportunity to customize the localized information presented in error alerts. NSResponder then forwards the message to the next responder, passing it the customized NSError object. The exact path up the modified responder chain depends on the type of application window:

Window owned by document: view > superviews > window > window controller > document object > document controller > the application object
Window with window controller but no documents: view > superviews > window > window controller > the application object
Window with no window controllers: view > superviews > window > the application object

NSApplication displays a document-modal error alert and, if the error object has a recovery attempter, gives it a chance to recover from the error. (A recovery attempter is an object that conforms to the NSErrorRecoveryAttempting informal protocol.)

Topics

Changing the First Responder

var acceptsFirstResponder: Bool

Whether the responder accepts first responder status.

func becomeFirstResponder()

Notifies the receiver that it’s about to become first responder in its NSWindow.

func resignFirstResponder()

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

func validateProposedFirstResponder(NSResponder, for: NSEvent?)

Allow controls to determine when they should become first responder.

Managing the Next Responder

var nextResponder: NSResponder?

The next responder after this one, or nil if it has none.

Responding to Mouse Events

func mouseDown(with: NSEvent)

Informs the receiver that the user has pressed the left mouse button.

func mouseDragged(with: NSEvent)

Informs the receiver that the user has moved the mouse with the left button pressed.

func mouseUp(with: NSEvent)

Informs the receiver that the user has released the left mouse button.

func mouseMoved(with: NSEvent)

Informs the receiver that the mouse has moved.

func mouseEntered(with: NSEvent)

Informs the receiver that the cursor has entered a tracking rectangle.

func mouseExited(with: NSEvent)

Informs the receiver that the cursor has exited a tracking rectangle.

func rightMouseDown(with: NSEvent)

Informs the receiver that the user has pressed the right mouse button.

func rightMouseDragged(with: NSEvent)

Informs the receiver that the user has moved the mouse with the right button pressed .

func rightMouseUp(with: NSEvent)

Informs the receiver that the user has released the right mouse button.

func otherMouseDown(with: NSEvent)

Informs the receiver that the user has pressed a mouse button other than the left or right one.

func otherMouseDragged(with: NSEvent)

Informs the receiver that the user has moved the mouse with a button other than the left or right button pressed.

func otherMouseUp(with: NSEvent)

Informs the receiver that the user has released a mouse button other than the left or right button.

Responding to Key Events

func keyDown(with: NSEvent)

Informs the receiver that the user has pressed a key.

func keyUp(with: NSEvent)

Informs the receiver that the user has released a key.

func interpretKeyEvents([NSEvent])

Invoked by subclasses from their keyDown(with:) method to handle a series of key events.

func performKeyEquivalent(with: NSEvent)

Overridden by subclasses to handle a key equivalent.

func flushBufferedKeyEvents()

Overridden by subclasses to clear any unprocessed key events.

Responding to Pressure Changes

func pressureChange(with: NSEvent)

Invoked when a pressure change occurs as the result of a user input event on a system that supports pressure sensitivity.

Responding to Other Kinds of Events

func cursorUpdate(with: NSEvent)

Informs the receiver that the mouse cursor has moved into a cursor rectangle.

func flagsChanged(with: NSEvent)

Informs the receiver that the user has pressed or released a modifier key (Shift, Control, and so on).

func tabletPoint(with: NSEvent)

Informs the receiver that a tablet-point event has occurred.

func tabletProximity(with: NSEvent)

Informs the receiver that a tablet-proximity event has occurred.

func helpRequested(NSEvent)

Displays context-sensitive help for the receiver if such exists; otherwise passes this message to the next responder.

func scrollWheel(with: NSEvent)

Informs the receiver that the mouse’s scroll wheel has moved.

func quickLook(with: NSEvent)

Implemented by subclasses to perform a Quick Look on the content at location in the event.

Responding to Action Messages

func cancelOperation(Any?)

Implemented by subclasses to cancel the current operation.

func capitalizeWord(Any?)

Implemented by subclasses to capitalize the word or words surrounding the insertion point or selection, expanding the selection if necessary.

func centerSelectionInVisibleArea(Any?)

Implemented by subclasses to scroll the selection, whatever it is, inside its visible area.

func changeCaseOfLetter(Any?)

Implemented by subclasses to change the case of a letter or letters in the selection, perhaps by opening a panel with capitalization options or by cycling through possible case combinations.

func complete(Any?)

Implemented by subclasses to complete an operation in progress or a partially constructed element.

func deleteBackward(Any?)

Implemented by subclasses to delete the selection, if there is one, or a single element backward from the insertion point (a letter or character in text, for example).

func deleteBackwardByDecomposingPreviousCharacter(Any?)

Implemented by subclasses to delete the selection, if there is one, or a single character backward from the insertion point.

func deleteForward(Any?)

Implemented by subclasses to delete the selection, if there is one, or a single element forward from the insertion point (a letter or character in text, for example).

func deleteToBeginningOfLine(Any?)

Implemented by subclasses to delete the selection, if there is one, or all text from the insertion point to the beginning of a line (typically of text).

func deleteToBeginningOfParagraph(Any?)

Implemented by subclasses to delete the selection, if there is one, or all text from the insertion point to the beginning of a paragraph of text.

func deleteToEndOfLine(Any?)

Implemented by subclasses to delete the selection, if there is one, or all text from the insertion point to the end of a line (typically of text).

func deleteToEndOfParagraph(Any?)

Implemented by subclasses to delete the selection, if there is one, or all text from the insertion point to the end of a paragraph of text.

func deleteToMark(Any?)

Implemented by subclasses to delete the selection, if there is one, or all items from the insertion point to a previously placed mark, including the selection itself if not empty.

func deleteWordBackward(Any?)

Implemented by subclasses to delete the selection, if there is one, or a single word backward from the insertion point.

func deleteWordForward(Any?)

Implemented by subclasses to delete the selection, if there is one, or a single word forward from the insertion point.

func indent(Any?)

Implemented by subclasses to indent the selection or the insertion point if there is no selection.

func insertBacktab(Any?)

Implemented by subclasses to handle a backward tab.

func insertContainerBreak(Any?)

Implemented by subclasses to insert a container break (typically a page break) at the insertion point or selection, deleting the selection if there is one.

func insertLineBreak(Any?)

Implemented by subclasses to insert a line break (as distinguished from a paragraph break) at the insertion point or selection, deleting the selection if there is one.

func insertNewline(Any?)

Implemented by subclasses to insert a newline character at the insertion point or selection, deleting the selection if there is one, or to end editing if the receiver is a text field or other field editor.

func insertNewlineIgnoringFieldEditor(Any?)

Implemented by subclasses to insert a line-break character at the insertion point or selection, deleting the selection if there is one.

func insertParagraphSeparator(Any?)

Implemented by subclasses to insert a paragraph separator at the insertion point or selection, deleting the selection if there is one.

func insertTab(Any?)

Implemented by subclasses to insert a tab character at the insertion point or selection, deleting the selection if there is one, or to end editing if the receiver is a text field or other field editor.

func insertTabIgnoringFieldEditor(Any?)

Implemented by subclasses to insert a tab character at the insertion point or selection, deleting the selection if there is one.

func insertDoubleQuoteIgnoringSubstitution(Any?)

Implemented by subclasses to insert a double quote character at the insertion point without interference by automatic quote correction.

func insertSingleQuoteIgnoringSubstitution(Any?)

Implemented by subclasses to insert a single quote character at the insertion point without interference by automatic quote correction.

func insertText(Any)

Overridden by subclasses to insert the supplied string at the insertion point or selection, deleting the selection if there is one.

func lowercaseWord(Any?)

Implemented by subclasses to make lowercase every letter in the word or words surrounding the insertion point or selection, expanding the selection if necessary.

func moveBackward(Any?)

Implemented by subclasses to move the selection or insertion point one element or character backward.

func moveBackwardAndModifySelection(Any?)

Implemented by subclasses to expand or reduce either end of the selection backward by one element or character.

func moveParagraphForwardAndModifySelection(Any?)

Implemented by subclasses to move the selection or insertion point to the beginning of the next paragraph, expanding or reducing the current selection.

func moveParagraphBackwardAndModifySelection(Any?)

Implemented by subclasses to move the selection or insertion point to the beginning of the previous paragraph, expanding or reducing the current selection.

func moveToBeginningOfDocumentAndModifySelection(Any?)

Implemented by subclasses to move the selection or insertion point to the beginning of the document, expanding or reducing the current selection.

func moveToEndOfDocumentAndModifySelection(Any?)

Implemented by subclasses to move the selection or insertion point to the end of the document, expanding or reducing the current selection.

func moveToBeginningOfLineAndModifySelection(Any?)

Implemented by subclasses to move the selection or insertion point to the beginning of the line, expanding or reducing the current selection.

func moveToEndOfLineAndModifySelection(Any?)

Implemented by subclasses to move the selection or insertion point to the end of the line, expanding or reducing the current selection.

func moveToBeginningOfParagraphAndModifySelection(Any?)

Implemented by subclasses to move the selection or insertion point to the beginning of the current paragraph, expanding or reducing the current selection.

func moveToEndOfParagraphAndModifySelection(Any?)

Implemented by subclasses to move the selection or insertion point to the end of the current paragraph, expanding or reducing the current selection.

func moveToLeftEndOfLine(Any?)

Implemented by subclasses to move the selection or insertion point to the left end of the line.

func moveToLeftEndOfLineAndModifySelection(Any?)

Implemented by subclasses to move the selection or insertion point to the left end of the line, expanding or contracting the selection as required.

func moveToRightEndOfLine(Any?)

Implemented by subclasses to move the selection or insertion point to the right end of the line

func moveToRightEndOfLineAndModifySelection(Any?)

Implemented by subclasses to move the selection or insertion point to the right end of the line, expanding or contracting the selection as required.

func moveDown(Any?)

Implemented by subclasses to move the selection or insertion point one element or character down.

func moveDownAndModifySelection(Any?)

Implemented by subclasses to expand or reduce the top or bottom end of the selection downward by one element, character, or line (whichever is appropriate for text direction).

func moveForward(Any?)

Implemented by subclasses to move the selection or insertion point one element or character forward.

func moveForwardAndModifySelection(Any?)

Implemented by subclasses to expand or reduce either end of the selection forward by one element or character.

func moveLeft(Any?)

Implemented by subclasses to move the selection or insertion point one element or character to the left.

func moveLeftAndModifySelection(Any?)

Implemented by subclasses to expand or reduce either end of the selection to the left (display order) by one element or character.

func moveRight(Any?)

Implemented by subclasses to move the selection or insertion point one element or character to the right.

func moveRightAndModifySelection(Any?)

Implemented by subclasses to expand or reduce either end of the selection to the right (display order) by one element or character.

func moveToBeginningOfDocument(Any?)

Implemented by subclasses to move the selection to the first element of the document or the insertion point to the beginning.

func moveToBeginningOfLine(Any?)

Implemented by subclasses to move the selection to the first element of the selected line or the insertion point to the beginning of the line.

func moveToBeginningOfParagraph(Any?)

Implemented by subclasses to move the insertion point to the beginning of the selected paragraph.

func moveToEndOfDocument(Any?)

Implemented by subclasses to move the selection to the last element of the document or the insertion point to the end.

func moveToEndOfLine(Any?)

Implemented by subclasses to move the selection to the last element of the selected line or the insertion point to the end of the line.

func moveToEndOfParagraph(Any?)

Implemented by subclasses to move the insertion point to the end of the selected paragraph.

func moveUp(Any?)

Implemented by subclasses to move the selection or insertion point one element or character up.

func moveUpAndModifySelection(Any?)

Implemented by subclasses to expand or reduce the top or bottom end of the selection upward by one element, character, or line (whichever is appropriate for text direction).

func moveWordBackward(Any?)

Implemented by subclasses to move the selection or insertion point one word backward.

func moveWordBackwardAndModifySelection(Any?)

Implemented by subclasses to expand or reduce either end of the selection backward by one whole word.

func moveWordForward(Any?)

Implemented by subclasses to move the selection or insertion point one word forward, in logical order.

func moveWordForwardAndModifySelection(Any?)

Implemented by subclasses to expand or reduce either end of the selection forward by one whole word.

func moveWordLeft(Any?)

Implemented by subclasses to move the selection or insertion point one word to the left, in display order.

func moveWordRight(Any?)

Implemented by subclasses to move the selection or insertion point one word right.

func moveWordRightAndModifySelection(Any?)

Implemented by subclasses to expand or reduce either end of the selection to the right by one whole word.

func moveWordLeftAndModifySelection(Any?)

Implemented by subclasses to expand or reduce either end of the selection left by one whole word in display order.

func pageDown(Any?)

Implemented by subclasses to scroll the receiver down (or back) one page in its scroll view, also moving the insertion point to the top of the newly displayed page.

func pageDownAndModifySelection(Any?)

Implemented by subclasses to scroll the receiver down (or back) one page in its scroll view, also moving the insertion point to the top of the newly displayed page. The selection is expanded or contracted as required.

func pageUp(Any?)

Implemented by subclasses to scroll the receiver up (or forward) one page in its scroll view, also moving the insertion point to the top of the newly displayed page.

func pageUpAndModifySelection(Any?)

Implemented by subclasses to scroll the receiver up (or forward) one page in its scroll view, also moving the insertion point to the top of the newly displayed page. The selection is expanded or contracted as necessary.

func quickLookPreviewItems(Any?)

Implemented by subclasses to perform a Quick Look on the text cursor position, selection, or whatever is appropriate for your view.

func scrollToBeginningOfDocument(Any?)

Implemented by subclasses to scroll the receiver to the beginning of the document, without changing the selection.

func scrollToEndOfDocument(Any?)

Implemented by subclasses to scroll the receiver to the end of the document, without changing the selection.

func scrollLineUp(Any?)

Implemented by subclasses to scroll the receiver one line up in its scroll view, without changing the selection.

func scrollLineDown(Any?)

Implemented by subclasses to scroll the receiver one line down in its scroll view, without changing the selection.

func scrollPageUp(Any?)

Implemented by subclasses to scroll the receiver one page up in its scroll view, without changing the selection.

func scrollPageDown(Any?)

Implemented by subclasses to scroll the receiver one page down in its scroll view, without changing the selection.

func selectAll(Any?)

Implemented by subclasses to select all selectable elements.

func selectLine(Any?)

Implemented by subclasses to select all elements in the line or lines containing the selection or insertion point.

func selectParagraph(Any?)

Implemented by subclasses to select all paragraphs containing the selection or insertion point.

func selectToMark(Any?)

Implemented by subclasses to select all items from the insertion point or selection to a previously placed mark, including the selection itself if not empty.

func selectWord(Any?)

Implemented by subclasses to extend the selection to the nearest word boundaries outside it (up to, but not including, word delimiters).

func setMark(Any?)

Implemented by subclasses to set a mark at the insertion point or selection, which is used by deleteToMark(_:) and selectToMark(_:).

func showContextHelp(Any?)

Implemented by subclasses to invoke the help system, displaying information relevant to the receiver and its current state.

func swapWithMark(Any?)

Swaps the mark and the selection or insertion point, so that what was marked is now the selection or insertion point, and what was the insertion point or selection is now the mark.

func transpose(Any?)

Transposes the characters to either side of the insertion point and advances the insertion point past both of them. Does nothing to a selected range of text.

func transposeWords(Any?)

Transposes the words to either side of the insertion point and advances the insertion point past both of them. Does nothing to a selected range of text.

func uppercaseWord(Any?)

Implemented by subclasses to make uppercase every letter in the word or words surrounding the insertion point or selection, expanding the selection if necessary.

func yank(Any?)

Replaces the insertion point or selection with text from the kill buffer.

func supplementalTarget(forAction: Selector, sender: Any?)

This method is used in the process of finding a target for an action method.

Handling Window Restoration

func encodeRestorableState(with: NSCoder)

Saves the interface-related state of the responder.

func restoreState(with: NSCoder)

Restores the interface-related state of the responder.

class var restorableStateKeyPaths: [String]

Returns an array of key paths representing the restorable attributes of the responder.

func invalidateRestorableState()

Marks the responder’s interface-related state as dirty.

Supporting User Activities

var userActivity: NSUserActivity?

An object encapsulating a user activity supported by this responder.

func restoreUserActivityState(NSUserActivity)

Restores the state needed to continue the given user activity.

func updateUserActivityState(NSUserActivity)

Updates the state of the given user activity.

Presenting and Customizing Error Information

func presentError(Error)

Presents an error alert to the user as an application-modal dialog.

func presentError(Error, modalFor: NSWindow, delegate: Any?, didPresent: Selector?, contextInfo: UnsafeMutableRawPointer?)

Presents an error alert to the user as a document-modal sheet attached to document window.

func willPresentError(Error)

Implemented by subclasses to return a custom version of the supplied error object that is more suitable for presentation in alert sheets and dialogs.

Dispatching Messages

func doCommand(by: Selector)

Attempts to perform the indicated command.

func `try`(toPerform: Selector, with: Any?)

Attempts to perform the action indicated method with a specified argument.

Managing a Responder’s Menu

var menu: NSMenu?

Returns the responder’s menu.

Updating the Services Menu

func validRequestor(forSendType: NSPasteboard.PasteboardType?, returnType: NSPasteboard.PasteboardType?)

Overridden by subclasses to determine what services are available.

Getting the Undo Manager

var undoManager: UndoManager?

The undo manager for this responder.

Testing Events

func shouldBeTreatedAsInkEvent(NSEvent)

Returns true if the specified event should be treated as an ink event, false if it should be treated as a mouse event.

Terminating the Responder Chain

func noResponder(for: Selector)

Handles the case where an event or action message falls off the end of the responder chain.

Touch and Gesture Events

func beginGesture(with: NSEvent)

Informs the receiver that the user has begun a touch gesture.

func endGesture(with: NSEvent)

Informs the receiver that the user has ended a touch gesture.

func magnify(with: NSEvent)

Informs the receiver that the user has begun a pinch gesture.

func rotate(with: NSEvent)

Informs the receiver that the user has begun a rotation gesture.

func swipe(with: NSEvent)

Informs the receiver that the user has begun a swipe gesture.

func touchesBegan(with: NSEvent)

Informs the receiver that new set of touches has been recognized.

func touchesMoved(with: NSEvent)

Informs the receiver that one or more touches has moved.

func touchesCancelled(with: NSEvent)

Informs the receiver that tracking of touches has been cancelled for any reason.

func touchesEnded(with: NSEvent)

Returns that a set of touches have been removed.

func wantsForwardedScrollEvents(for: NSEvent.GestureAxis)

Returns whether to forward elastic scrolling gesture events up the responder.

func smartMagnify(with: NSEvent)

Informs the receiver that the user performed a smart zoom gesture.

func wantsScrollEventsForSwipeTracking(on: NSEvent.GestureAxis)

Implement this method to track gesture scroll events such as a swipe.

Setting the Writing Direction

func makeBaseWritingDirectionLeftToRight(Any?)

Sets the paragraph base writing direction to be left to right.

func makeBaseWritingDirectionNatural(Any?)

Sets the paragraph base writing direction to be natural.

func makeBaseWritingDirectionRightToLeft(Any?)

Sets the paragraph base writing direction to be right to left.

func makeTextWritingDirectionLeftToRight(Any?)

Sets the character level attributed string direction attribute for left to right text.

func makeTextWritingDirectionNatural(Any?)

Removes the character-level writing direction attribute

func makeTextWritingDirectionRightToLeft(Any?)

Sets the character-level writing direction attribute to a single right-to-left embedding.

Performing Text Find Actions

func performTextFinderAction(Any?)

Performs all find oriented actions.

Initializers

init()

init?(coder: NSCoder)

Instance Properties

var touchBar: NSTouchBar?

The NSTouchBar object associated with the responder.

Instance Methods

func encodeRestorableState(with: NSCoder, backgroundQueue: OperationQueue)Beta

func makeTouchBar()

Your custom subclass of the NSResponder class should override this method to create and configure your subclass’s default NSTouchBar object.

func newWindowForTab(Any?)

Relationships

Inherits From

NSObject

Conforms To

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software