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 present​Error(_:​) and present​Error(_:​modal​For:​delegate:​did​Present:​context​Info:​) methods send will​Present​Error(_:​) 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.)

Symbols

Changing the First Responder

var accepts​First​Responder:​ Bool

Whether the responder accepts first responder status.

func become​First​Responder()

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

func resign​First​Responder()

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

func validate​Proposed​First​Responder(NSResponder, for:​ NSEvent?)

Allow controls to determine when they should become first responder.

Managing the Next Responder

var next​Responder:​ NSResponder?

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

Responding to Mouse Events

func mouse​Down(with:​ NSEvent)

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

func mouse​Dragged(with:​ NSEvent)

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

func mouse​Up(with:​ NSEvent)

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

func mouse​Moved(with:​ NSEvent)

Informs the receiver that the mouse has moved.

func mouse​Entered(with:​ NSEvent)

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

func mouse​Exited(with:​ NSEvent)

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

func right​Mouse​Down(with:​ NSEvent)

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

func right​Mouse​Dragged(with:​ NSEvent)

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

func right​Mouse​Up(with:​ NSEvent)

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

func other​Mouse​Down(with:​ NSEvent)

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

func other​Mouse​Dragged(with:​ NSEvent)

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

func other​Mouse​Up(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 key​Down(with:​ NSEvent)

Informs the receiver that the user has pressed a key.

func key​Up(with:​ NSEvent)

Informs the receiver that the user has released a key.

func interpret​Key​Events([NSEvent])

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

func perform​Key​Equivalent(with:​ NSEvent)

Overridden by subclasses to handle a key equivalent.

func flush​Buffered​Key​Events()

Overridden by subclasses to clear any unprocessed key events.

Responding to Pressure Changes

func pressure​Change(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 cursor​Update(with:​ NSEvent)

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

func flags​Changed(with:​ NSEvent)

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

func tablet​Point(with:​ NSEvent)

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

func tablet​Proximity(with:​ NSEvent)

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

func help​Requested(NSEvent)

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

func scroll​Wheel(with:​ NSEvent)

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

func quick​Look(with:​ NSEvent)

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

Responding to Action Messages

func cancel​Operation(Any?)

Implemented by subclasses to cancel the current operation.

func capitalize​Word(Any?)

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

func center​Selection​In​Visible​Area(Any?)

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

func change​Case​Of​Letter(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 delete​Backward(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 delete​Backward​By​Decomposing​Previous​Character(Any?)

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

func delete​Forward(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 delete​To​Beginning​Of​Line(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 delete​To​Beginning​Of​Paragraph(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 delete​To​End​Of​Line(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 delete​To​End​Of​Paragraph(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 delete​To​Mark(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 delete​Word​Backward(Any?)

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

func delete​Word​Forward(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 insert​Backtab(Any?)

Implemented by subclasses to handle a backward tab.

func insert​Container​Break(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 insert​Line​Break(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 insert​Newline(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 insert​Newline​Ignoring​Field​Editor(Any?)

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

func insert​Paragraph​Separator(Any?)

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

func insert​Tab(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 insert​Tab​Ignoring​Field​Editor(Any?)

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

func insert​Double​Quote​Ignoring​Substitution(Any?)

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

func insert​Single​Quote​Ignoring​Substitution(Any?)

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

func insert​Text(Any)

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

func lowercase​Word(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 move​Backward(Any?)

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

func move​Backward​And​Modify​Selection(Any?)

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

func move​Paragraph​Forward​And​Modify​Selection(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 move​Paragraph​Backward​And​Modify​Selection(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 move​To​Beginning​Of​Document​And​Modify​Selection(Any?)

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

func move​To​End​Of​Document​And​Modify​Selection(Any?)

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

func move​To​Beginning​Of​Line​And​Modify​Selection(Any?)

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

func move​To​End​Of​Line​And​Modify​Selection(Any?)

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

func move​To​Beginning​Of​Paragraph​And​Modify​Selection(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 move​To​End​Of​Paragraph​And​Modify​Selection(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 move​To​Left​End​Of​Line(Any?)

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

func move​To​Left​End​Of​Line​And​Modify​Selection(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 move​To​Right​End​Of​Line(Any?)

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

func move​To​Right​End​Of​Line​And​Modify​Selection(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 move​Down(Any?)

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

func move​Down​And​Modify​Selection(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 move​Forward(Any?)

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

func move​Forward​And​Modify​Selection(Any?)

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

func move​Left(Any?)

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

func move​Left​And​Modify​Selection(Any?)

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

func move​Right(Any?)

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

func move​Right​And​Modify​Selection(Any?)

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

func move​To​Beginning​Of​Document(Any?)

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

func move​To​Beginning​Of​Line(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 move​To​Beginning​Of​Paragraph(Any?)

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

func move​To​End​Of​Document(Any?)

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

func move​To​End​Of​Line(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 move​To​End​Of​Paragraph(Any?)

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

func move​Up(Any?)

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

func move​Up​And​Modify​Selection(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 move​Word​Backward(Any?)

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

func move​Word​Backward​And​Modify​Selection(Any?)

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

func move​Word​Forward(Any?)

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

func move​Word​Forward​And​Modify​Selection(Any?)

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

func move​Word​Left(Any?)

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

func move​Word​Right(Any?)

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

func move​Word​Right​And​Modify​Selection(Any?)

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

func move​Word​Left​And​Modify​Selection(Any?)

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

func page​Down(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 page​Down​And​Modify​Selection(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 page​Up(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 page​Up​And​Modify​Selection(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 quick​Look​Preview​Items(Any?)

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

func scroll​To​Beginning​Of​Document(Any?)

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

func scroll​To​End​Of​Document(Any?)

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

func scroll​Line​Up(Any?)

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

func scroll​Line​Down(Any?)

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

func scroll​Page​Up(Any?)

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

func scroll​Page​Down(Any?)

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

func select​All(Any?)

Implemented by subclasses to select all selectable elements.

func select​Line(Any?)

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

func select​Paragraph(Any?)

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

func select​To​Mark(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 select​Word(Any?)

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

func set​Mark(Any?)

Implemented by subclasses to set a mark at the insertion point or selection, which is used by delete​To​Mark(_:​) and select​To​Mark(_:​).

func show​Context​Help(Any?)

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

func swap​With​Mark(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 transpose​Words(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 uppercase​Word(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 supplemental​Target(for​Action:​ Selector, sender:​ Any?)

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

Handling Window Restoration

func encode​Restorable​State(with:​ NSCoder)

Saves the interface-related state of the responder.

func restore​State(with:​ NSCoder)

Restores the interface-related state of the responder.

class func restorable​State​Key​Paths()

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

func invalidate​Restorable​State()

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

Supporting User Activities

var user​Activity:​ NSUser​Activity?

An object encapsulating a user activity supported by this responder.

func restore​User​Activity​State(NSUser​Activity)

Restores the state needed to continue the given user activity.

func update​User​Activity​State(NSUser​Activity)

Updates the state of the given user activity.

Presenting and Customizing Error Information

func present​Error(Error)

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

func will​Present​Error(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 do​Command(by:​ Selector)

Attempts to perform the indicated command.

func `try`(to​Perform:​ 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 valid​Requestor(for​Send​Type:​ String, return​Type:​ String)

Overridden by subclasses to determine what services are available.

Getting the Undo Manager

var undo​Manager:​ Undo​Manager?

The undo manager for this responder.

Testing Events

func should​Be​Treated​As​Ink​Event(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 no​Responder(for:​ Selector)

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

Touch and Gesture Events

func begin​Gesture(with:​ NSEvent)

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

func end​Gesture(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 touches​Began(with:​ NSEvent)

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

func touches​Moved(with:​ NSEvent)

Informs the receiver that one or more touches has moved.

func touches​Cancelled(with:​ NSEvent)

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

func touches​Ended(with:​ NSEvent)

Returns that a set of touches have been removed.

func wants​Forwarded​Scroll​Events(for:​ NSEvent​Gesture​Axis)

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

func smart​Magnify(with:​ NSEvent)

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

func wants​Scroll​Events​For​Swipe​Tracking(on:​ NSEvent​Gesture​Axis)

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

Setting the Writing Direction

func make​Base​Writing​Direction​Left​To​Right(Any?)

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

func make​Base​Writing​Direction​Natural(Any?)

Sets the paragraph base writing direction to be natural.

func make​Base​Writing​Direction​Right​To​Left(Any?)

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

func make​Text​Writing​Direction​Left​To​Right(Any?)

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

func make​Text​Writing​Direction​Natural(Any?)

Removes the character-level writing direction attribute

func make​Text​Writing​Direction​Right​To​Left(Any?)

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

Performing Text Find Actions

func perform​Text​Finder​Action(Any?)

Performs all find oriented actions.

Instance Properties

var touch​Bar:​ NSTouch​Bar?

The NSTouch​Bar object associated with the responder.

Instance Methods

func make​Touch​Bar()

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

func new​Window​For​Tab(Any?)