Pop-up Menus

Pop-up menus can be created on Windows environments. Pop-up menus appear over the application in a vertical orientation while the user is clicking an item, and then they disappear from the screen. You can programmatically invoke a pop-up menu, or you can arrange for a right-mouse click to automatically invoke a pop-up menu tied to a window or a control. Each window and control can have its own pop-up menu. In addition, you can share a single menu between several windows and controls.

To create a pop-up menu, use the W$MENU routine with the WMENU-NEW-POPUP operation. This operation works just like WMENU-NEW, except that the resulting menu is a pop-up menu instead of a menu bar. Once created, pop-up menus are acted upon just like menu bars. Adding, changing, and deleting items is done in the same manner as for a menu bar, as is enabling or disabling items. If you want to add a submenu to a pop-up menu, you can use either a menu bar or another pop-up menu as the submenu.

To invoke a pop-up menu directly, use the WMENU-POPUP operation of W$MENU. The first operand is the handle of the menu you want to pop up. The menu is placed at the location of the mouse unless you specify two additional parameters, which are the absolute screen location (first row, then column). The screen location is expressed in pixels, with (1, 1) being the upper left-hand corner of the screen. This operation displays the menu, gets the user's selection (if any), and then removes the menu from the screen. The menu selection is placed into the run-time's input stream for future processing by an ACCEPT statement. This will appear to the ACCEPT statement just like a menu selection off of the menu bar.

You can automate the handling of pop-up menus by associating them with windows and controls. Each window and control can have its own pop-up menu associated with it. To do so, simply specify the menu handle in the POP-UP MENU phrase when you create the window or control. You can also add, change, or remove the pop-up menu later with the MODIFY statement.

When a window or control has a pop-up menu associated with it, the runtime will automatically display and handle this menu when the user clicks the right mouse button on the owning window or control. Your program will simply receive the menu selection in the input stream as if it came from the menu bar.

You can also detect pop-up menu selections directly in a control's event procedure. The following messages are generated as the user goes through the process of selecting a pop-up menu item:

MSG-INIT-MENU

Occurs immediately prior to the display of a control’s pop-up menu. EVENT-DATA-2 contains the control’s menu handle. The control’s event procedure can use this event to update any state information in the menu, such as enabling/disabling items or setting/removing check marks. If the event procedure sets EVENT-ACTION to EVENT-ACTION-FAIL, or sets the control’s menu handle to NULL, then the menu is not displayed. In this case, any host-defined built-in menu for the control class will display instead (e.g., Windows Cut/ Copy/Paste/Undo menu associated with entry fields). If there is no host-defined menu, then no menu is shown.

MSG-MENU-INPUT

Occurs when the user has activated a control’s pop-up menu and selected an item on the menu. EVENT-DATA-2 contains the menu item’s ID. Setting EVENT-ACTION to EVENT-ACTION-CONTINUE prevents further processing of the menu selection. Otherwise, the menu selection is treated as a normal menu selection from the menu bar (i.e., it terminates the ACCEPT with an exception value equal to the menu item’s ID).

MSG-END-MENU

Occurs when a control’s pop-up menu has been removed from the screen. EVENT-DATA-2 contains the control’s menu handle. The only normal reason for processing this event would be to undo some effect created in response to MSG-INIT-MENU.

Using MSG-MENU-INPUT, you can handle all of a control’s pop-up menu items directly in the control’s event procedure, without terminating any controlling ACCEPT statement.