X11 Work Bench Toolkit 1.0
For menus to be processed automatically by a Frame Window, you need to set up menu resources and callback function arrays.
The menu identifiers are atoms that are specified using plain text identifiers, both in the menu resource AND in the menu callback arrays. These callback arrays are assigned to both Frame Windows and Child Frames.
When a Child Frame has a menu assigned, or a menu callback array, whenever it is active its menu and/or callback array is used for automatic menu processing. Otherwise, the menu and/or callback array for the Frame Window will be used.
The Frame Window allows you to automatically specify a menu resource and menu callback array when you create it, via the FWCreateFrameWindow() function, and the FWSetMenuHandlers() function. You first create the window, and then assign its menu handlers whenever you need them. You can also assign different handlers for different application states, as necessary.
A typical menu resource might look like the following example:
This example shows top level menus for 'File', 'Tools', and 'Help' with a separator between 'Tools' and 'Help'. The '_' indicates that the next char will be displayed with an underscore, AND that it will act as a hotkey (top-level menus use Alt+char as the hotkey; popups can use other combinations).
To make the menu work, you need that callback array. For this menu, a simplified callback array is shown here (it uses macros for initialization):
The FW_MENU_HANDLER_BEGIN macro creates a variable 'main_menu_handlers' that is an array containing the menu handler information. Each entry following that has 3 parameters:
A menu UI callback returns a negative value to 'disable', or zero to 'enable' a menu item. Other capabilities are reserved for future use.
See Also: FW_MENU_HANDLER_ENTRY
The menu resources themselves consist of a set of lines, with several tab-delimited parameters on each line. The types of menu entries are:
Popups are each identified by their own resource, which begins with a single number followed by a linefeed, followed by additional menu resource information. In the example, there are 4 popup menus identified by the numbers '2' through '5'. These can invoke other popup menus, as needed.
Menu callback functions have prototypes similar to the following:
It will be invoked by passing in a Client Message event, where the Atom for 'pEvent->message_type' will be 'aMENU_COMMAND', and pEvent->data.l will contain the menu item's Atom. This way, it is possible to share the same callback function for multiple message identifiers, by checking the contents of the XClientMessageEvent to determine how to process it.
A menu UI callback function is declared similar to the following:
The 'pMenu' and 'pMenuItem' pointers identify the menu and menu item associated with the UI request. The function will return '1' to enable, or -1 to disable the menu item associated with the callback. A value of '0' is currently undefined, and will result in a behavior as if NO UI callback were defined.