---

Setting a Menu Item’s Key Equivalent

You can assign a keyboard equivalent to an NSMenuItem, so that when the user types a character the menu item sends its action. The keyboard equivalent is defined in two parts. First is the basic key equivalent, which must be a Unicode character that can be generated by a single key press without modifier keys (Shift excepted). It is also possible to use a sequence of Unicode characters so long as the user’s key mapping is able to generate the sequence with a single key press. The basic key equivalent is set using setKeyEquivalent: and returned by keyEquivalent. The second part defines the modifier keys that must also be pressed. This is set using setKeyEquivalentModifierMask: and returned by keyEquivalentModifierMask. The modifier mask by default includes NSCommandKeyMask, and may also include the masks for the Shift, Option, or other modifier keys. Specifying keyboard equivalents in two parts allows you to define a modified keyboard equivalent without having to know which character is generated by the basic key plus the modifier. For example, you can define the keyboard equivalent Command-Option-f without having to know which character is generated by typing Option-f.

Certain methods in NSMenuItem can override assigned keyboard equivalents with those the user has specified in the defaults system. The setUsesUserKeyEquivalents: method turns this behavior on or off, and usesUserKeyEquivalents returns its status. To determine the user-defined key equivalent for an NSMenuItem object, invoke the userKeyEquivalent instance method. If user-defined key equivalents are active and an NSMenuItem object has a user-defined key equivalent, its keyEquivalent method returns the user-defined key equivalent and not the one set using setKeyEquivalent:.

---