---

NSResponder Class Reference

Overview

NSResponder is an abstract class that forms the basis of event and command processing in the Application Kit. 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.

Starting with Mac OS X v10.4, NSResponder plays an important role in the presentation of error information. The default implementations of the presentError: and presentError:modalForWindow:delegate:didPresentSelector: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:

• Windows owned by document: view to superviews to window to window controller to document object to document controller to the application object

• Windows with window controllers but no documents: view to superviews to window to window controller to the application object

• Windows with no window controllers: view to superviews to window to 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.)

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

Tasks

Changing the First Responder

• – acceptsFirstResponder
• – becomeFirstResponder
• – resignFirstResponder

Managing the Next Responder

• – setNextResponder:
• – nextResponder

Responding to Mouse Events

• – mouseDown:
• – mouseDragged:
• – mouseUp:
• – mouseMoved:
• – mouseEntered:
• – mouseExited:
• – rightMouseDown:
• – rightMouseDragged:
• – rightMouseUp:
• – otherMouseDown:
• – otherMouseDragged:
• – otherMouseUp:

Responding to Key Events

• – keyDown:
• – keyUp:
• – interpretKeyEvents:
• – performKeyEquivalent:
• – performMnemonic:
• – flushBufferedKeyEvents

Responding to Other Kinds of Events

• – cursorUpdate:
• – flagsChanged:
• – tabletPoint:
• – tabletProximity:
• – helpRequested:
• – scrollWheel:

Responding to Action Messages

• – cancelOperation:
• – capitalizeWord:
• – centerSelectionInVisibleArea:
• – changeCaseOfLetter:
• – complete:
• – deleteBackward:
• – deleteBackwardByDecomposingPreviousCharacter:
• – deleteForward:
• – deleteToBeginningOfLine:
• – deleteToBeginningOfParagraph:
• – deleteToEndOfLine:
• – deleteToEndOfParagraph:
• – deleteToMark:
• – deleteWordBackward:
• – deleteWordForward:
• – indent:
• – insertBacktab:
• – insertContainerBreak:
• – insertLineBreak:
• – insertNewline:
• – insertNewlineIgnoringFieldEditor:
• – insertParagraphSeparator:
• – insertTab:
• – insertTabIgnoringFieldEditor:
• – insertText:
• – lowercaseWord:
• – moveBackward:
• – moveBackwardAndModifySelection:
• – moveDown:
• – moveDownAndModifySelection:
• – moveForward:
• – moveForwardAndModifySelection:
• – moveLeft:
• – moveLeftAndModifySelection:
• – moveRight:
• – moveRightAndModifySelection:
• – moveToBeginningOfDocument:
• – moveToBeginningOfLine:
• – moveToBeginningOfParagraph:
• – moveToEndOfDocument:
• – moveToEndOfLine:
• – moveToEndOfParagraph:
• – moveUp:
• – moveUpAndModifySelection:
• – moveWordBackward:
• – moveWordBackwardAndModifySelection:
• – moveWordForward:
• – moveWordForwardAndModifySelection:
• – moveWordLeft:
• – moveWordRight:
• – moveWordRightAndModifySelection:
• – moveWordLeftAndModifySelection:
• – pageDown:
• – pageUp:
• – scrollLineDown:
• – scrollLineUp:
• – scrollPageDown:
• – scrollPageUp:
• – selectAll:
• – selectLine:
• – selectParagraph:
• – selectToMark:
• – selectWord:
• – setMark:
• – showContextHelp:
• – swapWithMark:
• – transpose:
• – transposeWords:
• – uppercaseWord:
• – yank:

Presenting and Customizing Error Information

• – presentError:
• – presentError:modalForWindow:delegate:didPresentSelector:contextInfo:
• – willPresentError:

Dispatching Messages

• – doCommandBySelector:
• – tryToPerform:with:

Managing a Responder’s Menu

• – setMenu:
• – menu

Updating the Services Menu

• – validRequestorForSendType:returnType:

Getting the Undo Manager

• – undoManager

Testing Events

• – shouldBeTreatedAsInkEvent:

Terminating the Responder Chain

• – noResponderFor:

Setting the Interface Style

• – setInterfaceStyle:
• – interfaceStyle

Instance Methods

acceptsFirstResponder

Overridden by subclasses to return YES if the receiver accepts first responder status.

- (BOOL)acceptsFirstResponder

Discussion

As first responder, the receiver is the first object in the responder chain to be sent key events and action messages. The NSResponder implementation returns NO, indicating that by default a responder object doesn’t agree to become first responder.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – becomeFirstResponder
• – resignFirstResponder
• – needsPanelToBecomeKey (NSView)

Declared In

NSResponder.h

becomeFirstResponder

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

- (BOOL)becomeFirstResponder

Discussion

The default implementation returns YES, accepting first responder status. Subclasses can override this method to update state or perform some action such as highlighting the selection, or to return NO, refusing first responder status.

Use the NSWindow makeFirstResponder: method, not this method, to make an object the first responder. Never invoke this method directly.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – resignFirstResponder
• – acceptsFirstResponder

Declared In

NSResponder.h

cancelOperation:

Implemented by subclasses to cancel the current operation.

- (void)cancelOperation:(id)sender

Parameters

sender

The object invoking this method.

Discussion

This method is bound to the Escape and Command-. (period) keys. The key window first searches the view hierarchy for a view whose key equivalent is Escape or Command-., whichever was entered. If none of these views handles the key equivalent, the window sends a default action message of cancelOperation: to the first responder and from there the message travels up the responder chain.

If no responder in the responder chain implements cancelOperation:, the key window searches the view hierarchy for a view whose key equivalent is Escape (note that this may be redundant if the original key equivalent was Escape). If no such responder is found, then a cancel: action message is sent to the first responder in the responder chain that implements it.

NSResponder declares but does not implement this method.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSResponder.h

capitalizeWord:

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

- (void)capitalizeWord:(id)sender

Parameters

sender

The object invoking the method.

Discussion

If either end of the selection partially covers a word, that entire word is made lowercase. The sender argument is typically the object that invoked this method. NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – lowercaseWord:
• – uppercaseWord:
• – changeCaseOfLetter:

Declared In

NSResponder.h

centerSelectionInVisibleArea:

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

- (void)centerSelectionInVisibleArea:(id)sender

Parameters

sender

The object that invoked the method (typically).

Discussion

NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – scrollLineDown:
• – scrollLineUp:
• – scrollPageDown:
• – scrollPageUp:

Declared In

NSResponder.h

changeCaseOfLetter:

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.

- (void)changeCaseOfLetter:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – lowercaseWord:
• – uppercaseWord:
• – capitalizeWord:

Declared In

NSResponder.h

complete:

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

- (void)complete:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

This method can be interpreted, for example, as a request to attempt expansion of a partial word, such as for expanding a glossary shortcut, or to close a graphics item being drawn. NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

cursorUpdate:

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

- (void)cursorUpdate:(NSEvent *)event

Parameters

event

An object encapsulating information about the cursor-update event (NSCursorUpdate).

Discussion

Override this method to set the cursor image. The default implementation uses cursor rectangles, if cursor rectangles are currently valid.  If they are not, it calls super to send the message up the responder chain.

If the responder implements this method, but decides not to handle a particular event, it should invoke the superclass implementation of this method.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSResponder.h

deleteBackward:

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

- (void)deleteBackward:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

deleteBackwardByDecomposingPreviousCharacter:

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

- (void)deleteBackwardByDecomposingPreviousCharacter:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

If the previous character is canonically decomposable, this method should try to delete only the last character in the grapheme cluster (for example, deleting “a”+ “´” results in “a”). NSResponder declares but does not implement this method.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSResponder.h

deleteForward:

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

- (void)deleteForward:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

deleteToBeginningOfLine:

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

- (void)deleteToBeginningOfLine:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

Also places the deleted text into the kill buffer. NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – yank:

Declared In

NSResponder.h

deleteToBeginningOfParagraph:

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.

- (void)deleteToBeginningOfParagraph:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

Also places the deleted text into the kill buffer. NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – yank:

Declared In

NSResponder.h

deleteToEndOfLine:

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

- (void)deleteToEndOfLine:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

Also places the deleted text into the kill buffer. NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

deleteToEndOfParagraph:

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.

- (void)deleteToEndOfParagraph:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

Also places the deleted text into the kill buffer. NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – yank:

Declared In

NSResponder.h

deleteToMark:

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.

- (void)deleteToMark:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

Also places the deleted text into the kill buffer. NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setMark:
• – selectToMark:
• – yank:

Declared In

NSResponder.h

deleteWordBackward:

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

- (void)deleteWordBackward:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

deleteWordForward:

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

- (void)deleteWordForward:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

doCommandBySelector:

Attempts to perform the indicated command.

- (void)doCommandBySelector:(SEL)aSelector

Parameters

aSelector

The selector identifying the method.

Discussion

If the receiver responds to aSelector, it invokes the method with nil as the argument. If the receiver doesn’t respond, it sends this message to its next responder with the same selector. NSWindow and NSApplication also send the message to their delegates. If the receiver has no next responder or delegate, it beeps.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – tryToPerform:with:
• – sendAction:to:from: (NSApplication)

Declared In

NSResponder.h

flagsChanged:

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

- (void)flagsChanged:(NSEvent *)theEvent

Parameters

theEvent

An object encapsulating information about the modifier-key event.

Discussion

The default implementation simply passes this message to the next responder.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

flushBufferedKeyEvents

Overridden by subclasses to clear any unprocessed key events.

- (void)flushBufferedKeyEvents

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

helpRequested:

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

- (void)helpRequested:(NSEvent *)theEvent

Parameters

theEvent

An object encapsulating information about the help-request event.

Discussion

NSWindow invokes this method automatically when the user clicks for help—while processing theEvent. Subclasses need not override this method, and application code shouldn’t directly invoke it.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – showContextHelp:

Declared In

NSResponder.h

indent:

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

- (void)indent:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

insertBacktab:

Implemented by subclasses to handle a backward tab.”

- (void)insertBacktab:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

A field editor might respond to this method by selecting the field before it, while a regular text object either doesn’t respond to or ignores such a message. NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

insertContainerBreak:

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.

- (void)insertContainerBreak:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method. NSTextView implements it to insert an NSFormFeedCharacter character (0x000c).

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSResponder.h

insertLineBreak:

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.

- (void)insertLineBreak:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method. NSTextView implements it to insert an NSLineSeparatorCharacter character (0x2028).

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSResponder.h

insertNewline:

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.

- (void)insertNewline:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

insertNewlineIgnoringFieldEditor:

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

- (void)insertNewlineIgnoringFieldEditor:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

Unlike insertNewline:, this method always inserts a line-break character and doesn’t cause the receiver to end editing. NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

insertParagraphSeparator:

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

- (void)insertParagraphSeparator:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

insertTab:

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.

- (void)insertTab:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

insertTabIgnoringFieldEditor:

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

- (void)insertTabIgnoringFieldEditor:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

Unlike insertTab:, this method always inserts a tab character and doesn’t cause the receiver to end editing. NSResponder declares but doesn’t implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

insertText:

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

- (void)insertText:(id)aString

Parameters

aString

The string to insert or replace the selection with. aString can be either an NSString object or an NSAttributedString object.

Discussion

This method is often invoked by the system input manager after the receiver sends a interpretKeyEvents: message. The NSResponder implementation simply passes this message to the next responder, or beeps if there is no next responder.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

interfaceStyle

Returns the receiver’s interface style.

- (NSInterfaceStyle)interfaceStyle

Discussion

interfaceStyle is an abstract method in NSResponder and just returns NSNoInterfaceStyle. It is overridden in classes such as NSWindow and NSView to return the interface style, such as NSMacintoshInterfaceStyle. A responder’s style (if other than NSNoInterfaceStyle) overrides all other settings, such as those established by the defaults system.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setInterfaceStyle:

Declared In

NSInterfaceStyle.h

interpretKeyEvents:

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

- (void)interpretKeyEvents:(NSArray *)eventArray

Parameters

eventArray

An array of key-event characters to give to the system input manager.

Discussion

This method sends the character input in eventArray to the system input manager for interpretation as text to insert or commands to perform. The input manager responds to the request by sending insertText: and doCommandBySelector: messages back to the invoker of this method. Subclasses shouldn’t override this method.

See the NSInputManager and NSTextInput class and protocol specifications for more information on input management.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSResponder.h

keyDown:

Informs the receiver that the user has pressed a key.

- (void)keyDown:(NSEvent *)theEvent

Parameters

theEvent

An object encapsulating information about the key-down event.

Discussion

The receiver can interpret theEvent itself, or pass it to the system input manager using interpretKeyEvents:. The default im