You construct and control menus with the W$MENU library routine. You use the CALL statement to access this routine. The routine takes one or more parameters, which are always passed by REFERENCE (the default in COBOL). The first parameter is always an operation code. This code defines what the routine will do. The remaining parameters depend on the operation selected.
The operation codes are defined in the COPY file "acugui.def". The available codes are described here:
WMENU-NEW This operation constructs a new empty menu. W$MENU returns a handle for this menu in the special register RETURN-CODE. This handle should be stored in a variable declared as PIC S9(9) COMP-4. All future references to this menu are made by using this handle. This operation can fail if the system runs out of memory. In this case, RETURN-CODE will be set to zero.
WMENU-NEW-POPUP This operation constructs a new empty pop-up menu. W$MENU returns a handle for this menu in the special register WMENU-RESULT. This handle should be stored in a variable declared as PIC S9(9) COMP-4. All future references to this pop-up menu are made with this handle. This operation can fail if the system runs out of memory. In this case, WMENU-RESULT will be set to zero. This option is available for Windows systems only.
WMENU-POPUP This operation displays a pop-up menu and gets the user's response. After the user makes a selection, the pop-up menu is removed. (This is not the typical way to display a pop-up window. It is easier to assign the pop-up menu to a window or control and let the runtime handle activation.) The second parameter passed in conjunction with this operation code is the handle of the pop-up menu to show. The next two parameters are optional. If they are omitted, the menu appears where the mouse is currently located. If specified, they are the row and column (respectively) of the location where the menu should appear. This is expressed in screen base units (pixels under Windows), with "1,1" being the upper left corner of the physical screen. The user's response is sent to the current window and is treated as if it were a regular entry from the widow's menu bar. This option is available for Windows systems only.
WMENU-DESTROY You must pass the handle of a valid menu as the second parameter. That menu is destroyed and all memory it occupies is released. Any submenus that it contains are also destroyed. If the menu is currently being displayed, it is removed from the screen first. After destroying a menu, you must not use it any more. You should not destroy a submenu directly; use the WMENU-DELETE operation instead.
WMENU-ADD Adds a menu item to a menu. This operation takes several parameters. Note that all of the parameters are passed as integers (either USAGE DISPLAY or COMP-4) except for the "text" parameter, which is alphanumeric. You must use WMENU-SHOW to display an altered main menu bar. Additions to submenus are displayed the next time the submenu is selected.
The parameters are, in order:
handle - the handle of the menu to which you are adding the item. You can store the menu handle in a dedicated data type: USAGE HANDLE OF MENU.
position - the location at which you want to place the new item. If this value is zero, then the item is appended to the menu. Otherwise, this value is the ID of the item in front of which you want to insert the new item.
flags - this is a combination of one or more of the following:
W-CHECKED - indicates that a check mark or its equivalent should be placed beside the item. Check marks appear only on submenus.
W-DISABLED - indicates that the item may not be selected. It will appear gray on the menu or be distinguished in some way from other menu items.
W-SEPARATOR - indicates that this item consists of a bar that separates items on the menu. This item may not be selected by the user. The "text" field is ignored for this item. Separator bars may appear only on submenus.
You may combine flags by adding their values together. Values are defined in the file "acugui.def". The default value is zero, which indicates an enabled, un-checked menu item.
text - the text of the menu item that will appear on the menu bar. This text will appear exactly as you specify it, so be sure to use the desired case. (Graphical environments typically have conventions that you may want to follow, for consistency with other applications. For example, under Windows it is conventional to capitalize the first letter of each major word in a menu item.)
You may place an "&" symbol in front of the letter you want to use as the key letter for this menu item. The user can select this menu item by typing its key letter. The key letter typically appears underlined on the menu (you can change this appearance; see section 8.12).
If you omit the "&" symbol, then no underline will appear, and the first letter of the item will be used as the item's key letter. If the same key letter represents more than one item, and a user types that letter, the system will highlight the next menu item with that key letter and will wait for the user to confirm the selection by pressing <return>.
Displaying a shortcut key in the menu: A shortcut key is a keyboard key that you have designated in your program to perform the same action as a menu item. You must create a programmatic association between the menu item and the key. . One easy way to do this is to make the menu item's ID value the same as the exception value of the keystroke.
You may display the shortcut key's text next to the menu item in your menu if you want. To specify the shortcut key's text, place it immediately after the characters "\t" in the menu item's text. For example, if you want to create a menu item that has the text "Exit" and you want to display the shortcut key text "Ctl-X" next to it, you would specify "Exit\tCtl-X" as the item's text. You might think of "\t" as specifying a "tab" character that separates the two columns when they are displayed in the menu. If you need to include "\t" in your menu item's text, specify "\\t" to prevent it from being interpreted as a shortcut key indicator.
If "flags" contains the W-SEPARATOR option, you should either omit the text parameter or pass NULL, because a separator bar has no text.
id - this is an unsigned integer less than or equal to 4095 that you will use to identify this menu item. Use this ID anytime you need to refer to this menu item. This is the ID that's returned to your program when the item is selected by the user. Assign a unique ID to each item in a particular menu hierarchy. Normal (text) menu items must be given an ID. Submenu names and separator bars may optionally be given an ID of zero. These become anonymous menu items that you may never refer to again. If this parameter is omitted, an ID of zero is used.
A shortcut key is a keyboard key that you have designated in your program to perform the same action as a menu item. You must create a programmatic association between the menu item and the key. . One easy way to do this is to make the menu item's ID value the same as the exception value of the keystroke.
submenu - this parameter is omitted or set to zero for normal menu items and separator bars. You can create a submenu by setting this value to the handle of another menu. When the user selects this item, that other menu will pop up. Pop-up menus are placed down and to the right, unless they fit better in another position.
WMENU-CHANGE This operation takes the same parameters as WMENU-ADD (handle, position, flags, text, id, submenu). The "position" parameter must not be zero. It indicates the ID of the menu entry you want to change. That entry is deleted and the entry described by the current parameters is inserted in the same location. If the item that you are replacing is a submenu, that submenu's entries are also destroyed. If you change the main menu bar, you must use WMENU-SHOW to display the changed menu. Changes to submenus are displayed the next time the submenu is selected.
WMENU-DELETE Pass the handle of a menu as the second parameter, and the ID of an entry in that menu as the third parameter. The indicated entry is removed by this operation. If the deleted item is a submenu name, the submenu is also destroyed. If you change the main menu bar, you must use WMENU-SHOW to display the changed menu. Changes to submenus are displayed the next time the submenu is selected.
WMENU-CHECK This operation places a check mark or its equivalent in front of a menu item. You pass two additional parameters: the handle of the menu and the ID of the item you want to change. Only items that appear in submenus can have check marks.
WMENU-UNCHECK Use this operation to remove a check mark from a menu item. The second and third parameters are the handle of the menu and the ID of the item you want to change.
WMENU-DISABLE Use this operation to disable individual menu items. Disabled menu items are displayed with gray text or are distinguished in some way from other menu items. The second and third parameters are the menu's handle and the ID of the item you want to disable. You may disable items that appear on the top level of the menu. If you disable a submenu, then access to the submenu's items is denied. If you change the main menu bar, you must use WMENU-SHOW to display the changed menu.
WMENU-ENABLE Use this operation to enable a menu item. The second and third parameters are the menu's handle and the menu item's ID. If you change the main menu bar, you must use WMENU-SHOW to display the changed menu.
WMENU-SHOW Use this operation to display your menu on the screen. The second parameter is the handle of the menu you want to show. Use this operation both to display the menu initially and to display any changes made to the top level of the menu.
For example, if you disable one of the top-level menu items, then you must use WMENU-SHOW to make that change visible. If the application already has another menu showing when you call WMENU-SHOW, then that menu is removed. It is not destroyed; you may re-use that menu again later. If you pass a menu handle of zero, then any existing menu is removed and no new menu is shown, so passing a menu handle of zero is a way to clear all menus off the screen.
WMENU-REFRESH Use this operation to redraw an existing menu. This is typically used to restore a menu that has been overwritten by an external piece of software. For example, if you called the SYSTEM library routine to display the current directory, the directory listing might overwrite the menu. Use WMENU-REFRESH to redraw the menu when you are ready to see it again.
The following code fragment lists the files in the current directory on a UNIX machine and then restores the menu after the user presses <enter>:
* Prevent the user from activating the menu
CALL "W$MENU" USING WMENU-BLOCK.
* List the current files and wait for the user
CALL "SYSTEM" USING "ls".
DISPLAY "Listing complete. Press enter:", NO ADVANCING.
ACCEPT OMITTED.
*Redisplay the menu and turn it back on
CALL "W$MENU" USING WMENU-REFRESH.
CALL "W$MENU" USING WMENU-UNBLOCK.
WMENU-GET-MENU Sets RETURN-CODE to the handle of the currently displayed menu. This returns zero if no menu is currently displayed. Use this in routines that need to save the current menu before replacing it with their own menu.
WMENU-RELEASE This operation logically removes the menu from the screen, but doesn't update the screen. The menu is still visible, but not operational. This makes the entire screen available to your program, but doesn't scroll the current screen contents. This is occasionally useful when you need to remove a menu and clear the entire screen. If you instead use WMENU-SHOW to remove the menu, you'll have additional screen activity as it removes the menu bar and (if that bar was static) scrolls the screen. The screen update isn't needed if you are going to clear the whole screen anyway.
Under Windows, this function blocks the menu, but leaves it in place. The runtime uses this function just prior to shutting down.
This operation takes no parameters.
WMENU-GET-CONFIGURATION Returns the generic menu handler's current configuration. You must pass it one parameter that is laid out as described in section 8.12. This gets filled in with the current configuration. This operation sets RETURN-CODE to "1" if the configuration was retrieved. It sets RETURN-CODE to "0" if the host machine does not use the generic menu handler. In this case, the configuration information is not used and is meaningless.
WMENU-SET-CONFIGURATION You must pass one parameter to this operation that has the layout described in section 8.12. It causes this parameter to become the current configuration for the generic menu handler. It sets RETURN-CODE to "1" if the generic menu handler is being used, or "0" if it is not. In the latter case, the configuration will not be used.
If you have a menu displayed when you change the configuration, you should immediately use WMENU-SHOW to update that menu. Alternately, you may use WMENU-SHOW to remove that menu and display a new menu with the new configuration. If you have a menu displayed and change the configuration, you can get undefined results if you fail to use WMENU-SHOW.
WMENU-BLOCK This inhibits the menu. It works by maintaining a blocking-count. Initially, the blocking-count is set to zero. This call adds one to the blocking-count. Anytime the blocking-count is greater than zero, the user will not be allowed to use the menu. This is typically used by modal routines that need to ensure that the user completes some action before continuing. For example, if you are prompting for a file name, you might want to disable the menu until the user has entered a name. See also: WMENU-UNBLOCK, WMENU-GET-BLOCK, and WMENU-SET-BLOCK.
WMENU-UNBLOCK If the blocking-count is currently greater than zero, this subtracts one from the blocking-count. If this results in the blocking-count reaching zero, then the user will once again be able to use the menu. See also: WMENU-BLOCK, WMENU-GET-BLOCK, and WMENU-SET-BLOCK.
WMENU-GET-BLOCK Sets RETURN-CODE to the current blocking-count. This is typically used by routines that need to save the current menu state before replacing the menu with their own menu. They can save the blocking-count, set it to zero (with WMENU-SET-BLOCK), and then reset to the saved state when they exit. For example, the ACUCOBOL-GT debugger uses this call when replacing the application menu with its own menu. See also: WMENU-BLOCK, WMENU-UNBLOCK, and WMENU-SET-BLOCK.
WMENU-SET-BLOCK Sets the blocking-count to the value of the second parameter. Use this in conjunction with WMENU-GET-BLOCK to save and restore the current blocking-count. See also: WMENU-BLOCK, WMENU-UNBLOCK, WMENU-GET-BLOCK.
The W$MENU routine always sets RETURN-CODE. Except as described above, this is either "1" to indicate success or "0" to indicate that the operation failed.