NSMenuActionResponder

(informal protocol)

Category Of: NSObject

Declared In: AppKit/NSMenu.h

Protocol Description

This informal protocol allows your application to update the enabled or disabled status of an NSMenuCell. It declares only one method, validateCell:. By default, every time a user event occurs, NSMenu automatically enables and disables each visible menu cell based on criteria described later in this specification. Implement validateCell: in cases where you want to override NSMenu's default enabling scheme. This is described in more detail later.

There are two ways that NSMenuCells can be enabled or disabled: Explicitly, by sending the setEnabled: message, or automatically, as described below. NSMenuCells are updated automatically unless you send the message setAutoenablesItems:NO to the NSMenu object. You should never mix the two. That is, never use setEnabled: unless you have disabled the automatic updating.

Automatic Updating of NSMenuCells

Whenever a user event occurs, the NSMenu object updates the status of every visible menu cell. To update the status of a menu cell, NSMenu tries to find the object that responds to the NSMenuCell's action message. It searches the following objects in the following order until it finds one that responds to the action message.

. the NSMenuCell's target

. the key window's first responder

. the key window's delegate

. the main window's first responder

. the main window's delegate

. the NSApplication object

. the NSApplication's delegate

. the NSMenu's delegate

If none of these objects responds to the action message, the menu cell is disabled. If NSMenu finds an object that responds to the action message, it then checks to see if that object responds to the validateCell: message (the method defined in this informal protocol). If validateCell: is not implemented in that object, the menu cell is enabled. If it is implemented, the return value of validateCell: indicates whether the menu cell should be enabled or disabled.

For example, the NSText object implements the copy: method. If your application has a Copy menu cell that sends the copy: action message to the first responder, that menu cell is automatically enabled any time an NSText object is the first responder of the key or main window. If you have an object that might become the first responder and that object could allow users to select something that they aren't allowed to copy, you can implement the validateCell: method in that object. validateCell: can return NO if the forbidden items are selected and YES if they aren't. By implementing validateCell:, you can have the Copy menu item disabled even though its target object implements the copy: method. If instead your object never permits copying, then you would simply not implement copy: in that object, and the cell would be disabled automatically whenever the object is first responder.

If you send a setEnabled: message to enable or disable a menu cell when the automatic updating is turned on, other objects might reverse what you have done after another user event occurs. Using setEnabled:, you can never be sure that a menu cell is enabled or disabled or will remain that way. If your application must use setEnabled:, you must turn off the automatic enabling of menu cells (by sending setAutoEnablesItems:NO to NSMenu) in order to get predictable results.

Updating NSMenuCells

- (BOOL)validateCell:(id)aCell Implemented to override the default action of updating an NSMenuCell. Return YES to enable the NSMenuCell, NO to disable it.