Next Page > Hide TOC

NSResponder

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

Tasks

Constructors

• NSResponder

Changing the First Responder

• acceptsFirstResponder
• becomeFirstResponder
• resignFirstResponder

Setting the Next Responder

• setNextResponder
• nextResponder

Event Methods

• mouseDown
• mouseDragged
• mouseUp
• mouseMoved
• mouseEntered
• mouseExited
• rightMouseDown
• rightMouseDragged
• rightMouseUp
• otherMouseDown
• otherMouseDragged
• otherMouseUp
• scrollWheel
• keyDown
• keyUp
• flagsChanged
• helpRequested
• tabletPoint
• tabletProximity

Special Key Event Methods

• interpretKeyEvents
• performKeyEquivalent
• performMnemonic

Clearing Key Events

• flushBufferedKeyEvents

Action Methods

• showContextHelp

Dispatch Methods

• tryToPerform

Terminating the Responder Chain

• noResponderForSelector

Services Menu Updating

• validRequestorForTypes

Setting the Menu

• setMenu
• menu

Setting the Interface Style

• setInterfaceStyle
• interfaceStyle

Testing Events

• shouldBeTreatedAsInkEvent

Getting the Undo Manager

• undoManager

Presenting and Customizing Error Information

• presentError
• presentErrorModalForWindow
• willPresentError

Binding

• bind

Instance Methods

acceptsFirstResponder

Overridden by subclasses to return true if the receiver can handle key events and action messages sent up the responder chain.

public boolean acceptsFirstResponder()

Discussion

NSResponder’s implementation returns false, indicating that by default a responder object doesn’t agree to become first responder. Objects that aren’t first responder can receive mouse-down messages, but no other event or action messages.

See Also

• becomeFirstResponder
• resignFirstResponder
• needsPanelToBecomeKey (NSView)

becomeFirstResponder

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

public boolean becomeFirstResponder()

Discussion

NSResponder’s implementation returns true, accepting first responder status. Subclasses can override this method to update state or perform some action such as highlighting the selection, or to return false, refusing first responder status.

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

See Also

• resignFirstResponder
• acceptsFirstResponder

bind

Creates a relationship between the receiver’s binding and the property of observableController specified by keyPath.

public void bind(String binding, Object observableController, String keyPath, NSDictionary options)

Discussion

The binding is the key path for a property of the receiver previously exposed. The options dictionary is optional. If present, it contains placeholder objects or an NSValueTransformer identifier as described in “Constants.”

Availability

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

flagsChanged

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

public void flagsChanged(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

flushBufferedKeyEvents

Overridden by subclasses to clear any unprocessed key events.

public void flushBufferedKeyEvents()

helpRequested

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

public void helpRequested(NSEvent theEvent)

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.

See Also

• showContextHelp

interfaceStyle

Returns the receiver’s interface style.

public int interfaceStyle()

Discussion

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

See Also

• setInterfaceStyle

interpretKeyEvents

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

public void interpretKeyEvents(NSArray eventArray)

Discussion

This method sends the character input in eventArray to the system input manager for interpretation as text to insert or commands to perform. Subclasses shouldn’t override this method.

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

keyDown

Informs the receiver that the user has pressed a key.

public void keyDown(NSEvent theEvent)

Discussion

The receiver can interpret theEvent itself, or pass it to the system input manager using interpretKeyEvents. NSResponder’s implementation simply passes this message to the next responder.

keyUp

Informs the receiver that the user has released a key event specified by theEvent.

public void keyUp(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

menu

Returns the receiver’s menu.

public NSMenu menu()

Discussion

For NSApplication this menu is the same as the menu returned by its mainMenu method.

See Also

• setMenu
• menuForEvent (NSView)
• defaultMenu (NSView)

mouseDown

Informs the receiver that the user has pressed the left mouse button specified by theEvent.

public void mouseDown(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

mouseDragged

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

public void mouseDragged(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

mouseEntered

Informs the receiver that the cursor has entered a tracking rectangle specified by theEvent.

public void mouseEntered(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

mouseExited

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

public void mouseExited(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

mouseMoved

Informs the receiver that the mouse has moved specified by theEvent.

public void mouseMoved(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

See Also

• setAcceptsMouseMovedEvents (NSWindow)

mouseUp

Informs the receiver that the user has released the left mouse button specified by theEvent.

public void mouseUp(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

nextResponder

Returns the receiver’s next responder, or null if it has none.

public NSResponder nextResponder()

See Also

• setNextResponder
• noResponderForSelector

noResponderForSelector

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

public void noResponderForSelector(NSSelector eventSelector)

Discussion

NSResponder’s implementation beeps if eventSelector is keyDown.

otherMouseDown

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

public void otherMouseDown(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

otherMouseDragged

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

public void otherMouseDragged(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

otherMouseUp

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

public void otherMouseUp(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

performKeyEquivalent

Overridden by subclasses to handle a key equivalent.

public boolean performKeyEquivalent(NSEvent theEvent)

Discussion

If the character code or codes in theEvent match the receiver’s key equivalent, the receiver should respond to the event and return true. NSResponder’s implementation does nothing and returns false.

See Also

• performKeyEquivalent (NSView)
• performKeyEquivalent (NSButton)

performMnemonic

Overridden by subclasses to handle a mnemonic.

public boolean performMnemonic(String aString)

Discussion

If the character code or codes in aString match the receiver’s mnemonic, the receiver should perform the mnemonic and return true. NSResponder’s implementation does nothing and returns false. Mnemonics are not supported in Mac OS X.

See Also

• performMnemonic (NSView)

presentError

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

public boolean presentError(NSError anError)

Discussion

The alert displays information found in the NSError object anError; this information can include error description, recovery suggestion, failure reason, and button titles (all localized). The method returns true if error recovery succeeded and false otherwise.

The default implementation of this method sends willPresentError to self. By doing this, NSResponder gives subclasses an opportunity to customize error presentation. It then forwards the message, passing any customized error object, to the next responder; if there is no next responder, it passes the error object to NSApp, which displays a document-modal error alert. When the user dismisses the alert, any recovery attempter associated with the error object is given a chance to recover from the error. See the class description for the precise route up the responder chain (plus document and controller objects) this message might travel.

It is not recommended that you attempt to override this method. If you wish to customize the error presentation, override willPresentError instead.

Availability

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

See Also

• presentErrorModalForWindow

presentErrorModalForWindow

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

public void presentErrorModalForWindow(NSError error, NSWindow aWindow, Object delegate, NSSelector didPresentSelector, Object contextInfo)

Discussion

The aWindow parameter represents the window. The information displayed in the alert is extracted from the NSError object error; it may include a description, recovery suggestion, failure reason, and button titles (all localized). Once the user dismisses the alert and any recovery attempter associated with the error object has had a chance to recover from it, the receiver sends a message identified by didPresentSelector to the modal delegate delegate. (A recovery attempter is an object that conforms to the NSErrorRecoveryAttempting informal protocol.) The didPresentSelector selector must have the signature:

void didPresentErrorWithRecovery(boolean didRecover, Object contextInfo

The modal delegate implements this method to perform any post-error processing if recovery failed or was not attempted (that is, didRecover is NO). Any supplemental data is passed to the modal delegate via contextInfo.

The default implementation of this method sends willPresentError to self. By doing this, NSResponder gives subclasses an opportunity to customize error presentation. It then forwards the message, passing any customized error, to the next responder or; if there is no next responder, it passes the error object to NSApp, which displays a document-modal error alert. When the user dismisses the alert, any recovery attempter associated with the error object is given a chance to recover from the error. See the class description for the precise route up the responder chain (plus document and controller objects) this message might travel.

It is not recommended that you attempt to override this method. If you wish to customize the error presentation, override willPresentError instead.

Availability

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

See Also

• presentError

resignFirstResponder

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

public boolean resignFirstResponder()

Discussion

NSResponder’s implementation returns true, resigning first responder status. Subclasses can override this method to update state or perform some action such as unhighlighting the selection, or to return false, refusing to relinquish first responder status.

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

See Also

• becomeFirstResponder
• acceptsFirstResponder

rightMouseDown

Informs the receiver that the user has pressed the right mouse button specified by theEvent.

public void rightMouseDown(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

rightMouseDragged

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

public void rightMouseDragged(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

rightMouseUp

Informs the receiver that the user has released the right mouse button specified by theEvent.

public void rightMouseUp(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

scrollWheel

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

public void scrollWheel(NSEvent theEvent)

Discussion

NSResponder’s implementation simply passes this message to the next responder.

setInterfaceStyle

Sets the receiver’s style to the style specified by interfaceStyle, such as NSInterfaceStyle.MacintoshInterfaceStyle or NSInterfaceStyle.Windows95InterfaceStyle.

public void setInterfaceStyle(int interfaceStyle)

Discussion

setInterfaceStyle is an abstract method in NSResponder, but is overridden in classes such as NSWindow and NSView to actually set the interface style. You should almost never need to invoke or override this method, but if you do override it, your version should always invoke the implementation in super.

See Also

• interfaceStyle

setMenu

Sets the receiver’s menu to aMenu.

public void setMenu(NSMenu aMenu)

Discussion

If the receiver is an NSApplication object, this method sets the main menu, typically set using setMainMenu.

See Also

• menu

setNextResponder

Sets the receiver’s next responder to aResponder.

public void setNextResponder(NSResponder aResponder)

See Also

• nextResponder

shouldBeTreatedAsInkEvent

Returns true if theEvent should be treated as an ink event, false if theEvent should be treated as a mouse event.

public boolean shouldBeTreatedAsInkEvent(NSEvent theEvent)

Discussion

This provides the ability to distinguish when a pen-down should start inking versus when a pen-down should be treated as a mouse down event. This allows for a write-anywhere model for pen-based input.

The default implementation in NSApplication sends the method to the NSWindow under the pen. If the window is inactive, this method returns true, unless the pen-down is in the window drag region. If the window is active, this method is sent to the NSView under the pen.

The default implementation in NSView returns true, and NSControl overrides and returns false. This allows write-anywhere over most NSViews, but allows the pen to be used to track in controls and to move windows.

A custom view should override this method to get the correct behavior for a pen-down in the view.

Availability

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

showContextHelp

Implemented by subclasses to invoke the help system, displaying information relevant to the receiver and its current state. The sender argument is typically the object that invoked this method.

public void showContextHelp(Object sender)

See Also

• helpRequested

tabletPoint

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

public void tabletPoint(NSEvent theEvent)

Discussion

Tablet events are represented by NSEvent objects of type NSTabletPoint. They describe the current state of a transducer (that is, a pointing device) that is in proximity to its tablet, reflecting changes such as location, pressure, tilt, and rotation. See “NSEvent” for the methods that allow you to extract this and other information from theEvent. The default implementation of NSResponder passes the message to the next responder.

Availability

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

See Also

• tabletProximity

tabletProximity

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

public void tabletProximity(NSEvent theEvent)

Discussion

Tablet events are represented by NSEvent objects of type NSTabletProximity. Tablet devices generate proximity events when the transducer (pointing device) nears a tablet and when it moves away from a tablet. From an event object of this type you can extract information about the kind of device and its capabilities, as well as the relation of this tablet-proximity event to various tablet-point events; see “NSEvent” for details. The default implementation of NSResponder passes the message to the next responder.

Availability

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

See Also

• tabletPoint

tryToPerform

Attempts to perform the action method indicated by anAction.

public boolean tryToPerform(NSSelector anAction, Object anObject)

Discussion

The method should take a single argument of type Object and return void. If the receiver responds to anAction, it invokes the method with anObject as the argument and returns true. If the receiver doesn’t respond, it sends this message to its next responder with the same selector and object. Returns false if no responder is found that responds to anAction.

See Also

• sendActionToTargetFromSender (NSApplication)

undoManager

Returns the undo manager for this responder.

public NSUndoManager undoManager()

Discussion

NSResponder’s implementation simply passes this message to the next responder.

validRequestorForTypes

Overridden by subclasses to determine what services are available.

public Object validRequestorForTypes(String sendType, String returnType)

Discussion

With each event, and for each service in the Services menu, the application object sends this message up the responder chain with the send and return type for the service being checked. This method is therefore invoked many times per event. If the receiver can place data of sendType on the pasteboard and receive data of returnType, it should return this; otherwise it should return either super.validRequestorForTypes() or nextResponder().validRequestorForTypes(), which allows an object higher up in the responder chain to have an opportunity to handle the message. NSResponder’s implementation simply forwards this message to the next responder, ultimately returning null.

Either sendType or returnType—but not both—may be empty. If sendType is empty, the service doesn’t require input from the application requesting the service. If returnType is empty, the service doesn’t return data.

See Also

• registerServicesMenuTypes (NSApplication)

willPresentError

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

public NSError willPresentError(NSError anError)

Discussion

The default implementation of this method simply returns anError unchanged. When overriding this method, you can examine anError and, if its localized description or recovery information is unhelpfully generic, return an error object with more specific localized text. If you do this, always use the domain and error code of the NSError object to distinguish between errors whose presentation you want to customize and those you do not. Don’t make decisions based on the localized description, recovery suggestion, or recovery options because parsing localized text is problematic. If you decide not to customize the error presentation, return by sending this message to super.

Availability

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

See Also

• presentError

Next Page > Hide TOC