W$MENU

You construct and control menus with the W$MENU library routine. You use the CALL statement to access this routine.

Usage

CALL "W$MENU"
    USING OP-CODE, parameters,
    GIVING WMENU-RESULT

Parameters

OP-CODE Numeric parameter This indicates the desired operation. Level 78 symbolic names for these operations can be found in acugui.def.
parameters Vary depending on the op-code chosen
WMENU-RESULT PIC S9(9) Holds the return value from W$MENU. A value of zero indicates failure for all operations.

Description

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:

OP-CODE Numeric parameter This indicates the desired operation. Level 78 symbolic names for these operations can be found in acugui.def.
parameters Vary depending on the op-code chosen
WMENU-RESULT PIC S9(9) Holds the return value from W$MENU. A value of zero indicates failure for all operations.
WMENU-NEW This operation constructs a new empty menu bar. W$MENU returns a handle for this menu bar 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 menu bar 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.
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-DESTROY-DELAYED    You must pass the handle of a valid menu as the second parameter. If that menu is not being displayed, the 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 not destroyed immediately. Instead, it is marked for destruction later. It is actually destroyed immediately after the next WMENU-SHOW operation. 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 menu at the top level.

The parameters are, in order:

  • Handle - This is the handle of the menu to which you are adding the item.
  • Position - This is 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 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.
    • 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 0, which indicates an enabled, unchecked menu item.

  • Text - This is the text of the menu item that will appear on the menu bar. Text is limited to 50 characters. The 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 pressing <Alt> and typing its key letter. The key letter typically appears underlined on the menu (you can change this appearance; see the topic Menu Configuration With the Generic Menu Handler in ACUCOBOL-GT User Interface Programming).

    If you omit the "&" symbol, 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>. If flags contains the W-SEPARATOR option, you should either omit this parameter or pass NULL.

  • 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.
  • 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, and 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.
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.
WMENU-CHECK This operation places a check mark 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. 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. If you call W$MENU using this option, and pass the menu's main handle, without specifying an item on the menubar, the entire menu bar is disabled.
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 a menu bar on the screen. The first parameter after the op-code is the handle of the menu bar to show. The second parameter (optional) is the handle of the window on which to display the menu. If the second parameter is omitted, the menu is displayed on the current window. Use this operation both to display the menu bar 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 bar showing when you call WMENU-SHOW, then that menu bar is removed. It is not destroyed--you may re-use that menu bar again later. If you pass a menu handle of zero, then any existing menu bar is removed and no new menu bar is shown, so passing a menu handle of zero is a way to clear all menu bars 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.
WMENU-GET-MENU Sets WMENU-RESULT 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 bar 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 bar and clear the entire screen. If you instead use WMENU-SHOW to remove the menu bar, 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 bar, 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 has the layout described in the next section. This gets filled in with the current configuration. This operation sets WMENU-RESULT to 1 if the configuration was retrieved. It sets WMENU-RESULT 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 the next section. It causes this parameter to become the current configuration for the generic menu handler. It sets WMENU-RESULT 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 WMENU-RESULT 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, and WMENU-GET-BLOCK.

The W$MENU routine always sets WMENU-RESULT. Except as described above, this is either 1 to indicate success or 0 to indicate that the operation failed.

The ACUCOBOL-GT generic menu handler allows you to configure several aspects of its look and feel. This is done with get/set configuration operations described in the previous section. For both of these operations, you must pass a parameter that has the following layout: 

01 MENU-CONFIGURATION.
   03 MENU-STYLE                         PIC 9 COMP-X.
      88 MENU-IS-STATIC                  VALUE 0.
      88 MENU-IS-POPUP                   VALUE 1.
   03 MENU-CHECK-MARK                    PIC X.
   03 MENU-SUBMENU-MARK                  PIC X.
   03 MENU-COLOR-ATTRIBUTES.
      05 MENU-NORMAL-COLOR-ATTRIBUTES.
         07 MENU-NORMAL-COLOR            PIC 9(4) COMP-X.
         07 MENU-NORMAL-COLOR-KEY-1      PIC 9(4) COMP-X.
         07 MENU-NORMAL-COLOR-KEY-2      PIC 9(4) COMP-X.
      05 MENU-SELECTED-COLOR-ATTRIBUTES.
         07 MENU-SELECTED-COLOR          PIC 9(4) COMP-X.
         07 MENU-SELECTED-COLOR-KEY-1    PIC 9(4) COMP-X.
         07 MENU-SELECTED-COLOR-KEY-2    PIC 9(4) COMP-X.
      05 MENU-DISABLED-COLOR-ATTRIBUTES.
         07 MENU-DISABLED-COLOR          PIC 9(4) COMP-X.
         07 MENU-DISABLED-COLOR-KEY-1    PIC 9(4) COMP-X.
         07 MENU-DISABLED-COLOR-KEY-2    PIC 9(4) COMP-X.
   03 MENU-MONO-ATTRIBUTES.
      05 MENU-NORMAL-MONO-ATTRIBUTES.
         07 MENU-NORMAL-MONO             PIC 9(4) COMP-X.
         07 MENU-NORMAL-MONO-KEY-1       PIC 9(4) COMP-X.
         07 MENU-NORMAL-MONO-KEY-2       PIC 9(4) COMP-X.
      05 MENU-SELECTED-MONO-ATTRIBUTES.
         07 MENU-SELECTED-MONO           PIC 9(4) COMP-X.
         07 MENU-SELECTED-MONO-KEY-1     PIC 9(4) COMP-X.
         07 MENU-SELECTED-MONO-KEY-2     PIC 9(4) COMP-X.
      05 MENU-DISABLED-MONO-ATTRIBUTES.
         07 MENU-DISABLED-MONO           PIC 9(4) COMP-X.
         07 MENU-DISABLED-MONO-KEY-1     PIC 9(4) COMP-X.
         07 MENU-DISABLED-MONO-KEY-2     PIC 9(4) COMP-X.

A copy of this data item can be found in acugui.def.

When a menu is shown, the current configuration defines how it is presented. The fields have the following meaning:

  • MENU-STYLE - Determines whether the menu is static (value "0) or pop-up (value 1). The default is static.
  • MENU-CHECK-MARK - Sets the character used to display check marks. The default character is an asterisk.
  • MENU-SUBMENU-MARK - Sets the character used to indicate that the item is a submenu. This is not used on the main menu bar. The default character is a greater-than sign.
  • MENU-COLOR-ATTRIBUTES - Defines the display attributes used if the station supports color. This is described in detail below.
  • MENU-MONO-ATTRIBUTES - Defines the display attributes used if the station is monochrome. See below for details.

    Notice that there are two sets of attributes, one for color stations and one for monochrome stations. Within each set, there are three group items that determine the attributes used for a particular case. Using color stations as an example, we have:

  • MENU-NORMAL-COLOR-ATTRIBUTES - Determines the attributes used for the normal menu items. This is used for the menu's background color along with all items that are not highlighted or disabled.
  • MENU-SELECTED-COLOR-ATTRIBUTES - Determines the attributes used for the currently selected (highlighted) menu items.
  • MENU-DISABLED-COLOR-ATTRIBUTES - Determines the attributes used by disabled menu items.

    Finally, within each group, there are three fields that determine the attributes used for the appropriate menu items. For example, with normal menu items on a color station, we have:

  • MENU-NORMAL-COLOR - This is the attribute used to draw the menu item and its background.
  • MENU-NORMAL-COLOR-KEY-1 - This is the attribute used to draw the key letter in the menu item (if any).
  • MENU-NORMAL-COLOR-KEY-2  - This is used only if MENU-NORMAL-COLOR-KEY-1 contains the underline attribute and the station does not support underlining. In this case, the actual attribute used is determined by this field.

This scheme of having two possible attributes available for the key letter makes it easier to implement a portable set of attributes. Traditionally, key letters are shown underlined, and so underlining is typically used in the KEY-1 attribute. Since many stations do not support underlining, having a second attribute provides a backup system.

Attributes are set using the same scheme as that used for the COLOR phrase in an ACCEPT or DISPLAY statement. The only exception is that the Protected attribute (32768) has a special meaning when used in conjunction with disabled menu items. If you specify protected as the disabled item's color, then disabled items will appear in parentheses on the menu. This helps distinguish them from normal items.

Attribute values are numeric. They represent combinations of colors and other video features such as intensity. You make combinations by adding appropriate values together from these tables:
Color Foreground Background
Black 1 32
Blue 2 64
Green 3 96
Cyan 4 128
Red 5 160
Magenta    6 192
Brown 7 224
White 8 256
Attribute Value
Reverse video    1024
Low intensity 2048
High intensity 4096
Underline 8192
Blink 16384
Protected 32768
Parent topic: General Syntax and Library List