Event XbpMenuBar():onMenuKey

Notifies the application about a menu shortcut.

:onMenuKey := {| nKeyCode, uNil, self | ... } --> nProcess
:onMenuKey( nKeyCode ) --> nProcess
xbeMENB_OnMenuKey (1048964)

Parameter <nKeyCode> specifies the numeric key code of the pressed key.

This method returns a numerical value to specify whether the application recognizes the character pressed as a menu shortcut key. See below for a discussion of the possible return values.

With regular menu items, a character must be preceded with a tilde (~) in order to be recognized as a menu shortcut character. Whenever such a key is pressed while the menu is active, the system automatically activates the corresponding menu item. If owner-drawing is selected for a menu item, however, it is the application's responsibility to define the menu item's caption. Processing the xbeMENB_OnMenuKey notification allows an application to associate a shortcut character with a menu item, even if no caption was specified when calling the method XbpMenubar:addItem().

If a menu is active and a key is pressed that cannot be attributed to a menu item, the system sends the application a xbeMENB_OnMenuKey notification. Parameter <nKeyCode> contains the numeric code of the key pressed. Once it receives the notification, the application can examine the key code passed to determine whether it matches a shortcut character of one of the menu items defined. After processing, the application returns a numeric value that specifies how the key press should be handled by the system.

Value	Description
0	Discard key, output beep on system speaker
1	Close active menu
2	Parameter <nKeyCode> specifies index of menu item to be activated

The :onMenuKey() callback method in the XbpMenubar class enumerates all owner-drawn menu items defined for the XbpMenubar object. If an item is found whose shortcut character is the character passed in <nKeyCode>, the handler returns the value 2. Furthermore, the handler assigns the item's index to parameter <nKeyCode>. If the menu does not contain a matching item, the callback method :onMenuKey()returns 1.

To customize processing of the xbeMENB_OnMenuKey event, the callback method :onMenuKey() can be redefined in user defined subclasses. To alter the default processing performed by the XbpMenubar class itself (not a derived class), a code block must be assigned to the :onMenuKey callback slot.

The xbeMENB_OnMenuKey notification is sent synchronously via the XbpMenubar object's :handleEvent() method. The event code xbeMENB_OnMenuKey will not be returned by the function AppEvent(). In addition, Xbase Parts are created and maintained by a special system thread called the UI thread. Both the :onMenuKey() callback method and the :onMenuKey callback code block are executed on that thread. The application must therefore assume all thread-local settings to contain default values. For instance, a work area opened in an application thread may not be available.

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Event XbpMenuBar():onMenuKey Foundation