The Menu Design Tool is part of the Screen Management Facility (SMF) in ACCENT R. It allows menu-driven applications to be designed and implemented without procedural coding.
Follow these steps to design, display, and process a menu in an application.
1. Define the menu and its items in a LAYOUT SCREEN segment (MENU LAYOUT SCREEN).
The LAYOUT SCREEN segment is a group of statements that are specified in a Process Module (PM) Declare Section, a Global Storage (GS), or a Code Segment (CS). The statements in a LAYOUT SCREEN segment define:
- the size and rendition of the menu
- the list of items in the menu that the user can select
- for each item, a trigger to execute when the item is chosen
- for each item, a help box or a help trigger
- messages in the menu
- horizontal and vertical lines
- boxes
2. Create the menu with the GENERATE statement/command.
The GENERATE statement in a PM or the GENERATE command checks the syntax of the LAYOUT SCREEN segment and creates the menu. If the syntax is correct, SMF compiles the menu and stores it in an internal table.
When the menu is created, GENERATE returns a menu ID (identification number) that is used in subsequent commands/statements and functions to identify the menu. The menu ID is a unique non-zero value that lasts throughout the ACCENT R session if it is stored globally (such as in a GS ).
It is recommended that the value of the menu ID be stored in a GS field. If the menu ID is stored globally, the menu can be used by different PM’s or Command Modules (CM) within the same ACCENT R session. To restart a menu, issue a MENU statement/ command with the proper menu ID without going through another GENERATE. This allows the menu operation to be repeatedly invoked in the same ACCENT R session without regenerating the menu.
3. Start the menu operation with a MENU statement/command.
Once the menu has been successfully generated, execute the MENU statement/command to perform the menu operation. If there are other forms, menus, or windows already displayed on the screen, the new menu may overlay them. The user makes a selection by moving the cursor to an item and pressing the Return key menu operation windows overlapping. The developer specifies what happens when the user makes a selection by associating a trigger to an item.
In a PM, a trigger can be associated to each menu item with a PERFORM substatement in the LAYOUT SCREEN segment. If the /ALWAYS/ BEFORE clause is used with PERFORM, the trigger will be executed as soon as the user moves the cursor to the item. If the clause is not used, the user must press the Return Key when the cursor is on the item before the trigger is executed. The trigger could paste another menu or start an application or direct it to re-perform the menu.
After the trigger is executed, ACCENT R resumes the menu operation. Optionally, the system field, @MENU_ACTION, can be set within the performed trigger to control what happens after the trigger completes execution. If a value is not assigned to @MENU_ACTION, the cursor moves to the first item in the menu and waits for the user to make another selection. Here are the values that @MENU_ACTION can be set to:
- REDO causes the cursor to stay at the currently selected menu item after returning from the trigger.
- END causes the menu operation to terminate after the trigger completes execution with the current item indicated in @MENU_CHOICE.
If an item is selected but a trigger is not specified for it, the menu operation terminates and the menu is removed from the screen. The next statement (after the MENU statement) is then executed. The menu can be left on the screen if it was “pasted” before executing the MENU statement.
The value of the system fields @MENU_CHOICE and @MENU_KEYWORD can be examined to determine which menu item was most recently selected. Appropriate action can then be taken, based on the selection. The values in these system fields are:
- @MENU_CHOICE - stores sequence number of the selected item. Menu items are numbered in the order that they appear in the LAYOUT SCREEN segment, not in the order that they appear on the screen. If the selected item is the second ITEM statement in the LAYOUT SCREEN segment, the value of @MENU_CHOICE is 2.
- @MENU_KEYWORD stores value of the associated KEYWORD sub-statement.
In a CM, the value of the system field @MENU_CHOICE or @MENU_KEYWORD can be examined to determine the menu item that was selected.
In a PM, a trigger can be assigned to perform (or specify a window to display) when the user positions the cursor on a menu item and presses the help keycode. In a CM, a window can be specified to display when the user presses the help keycode. The help keycode is stored in the system field @HELP_CODE and can be changed.
4. Ending the menu operation.
If an item is selected and a trigger is not specified for it or if an item trigger is executed that sets "END" to @MENU_ACTION, the menu operation terminates and the menu is removed from the screen. The statement following the MENU statement is then executed menu operation ending @MENU_ACTION.
5. Use the Window Control Tools with the Menu.
The menu can be dynamically modified using the Window Control Tools. Some examples of what can be done is listed below. See the Window Control Tools section for more information.
- PREVIEW A MENU - Use the SCREEN PASTE_WINDOW statement/command to display a menu without starting a menu operation.
- KEEP A MENU PASTED - Use SCREEN PASTE_WINDOW to put the menu on the screen before executing the MENU statement/command so that the menu is not removed from the screen after normal termination.
When a menu has been pasted in this way, the only way to remove it from the screen is to execute SCREEN UNPASTE_WINDOW.
If the menu is displayed by SCREEN PASTE_WINDOW, the subsequent execution of MENU will not redisplay the menu even if the menu's display position is different from its pasted position.
REMOVE A MENU - There are several ways to remove a menu before its normal termination. Keep in mind that a menu can have other windows associated with it, such as help boxes.
- SCREEN DELETE_WINDOW removes a menu, but does not remove its associated windows.
- FLUSH removes a menu and all its associated windows.
- SCREEN KILL_SCREEN removes all generated menus (after execution, saved menu ID’s for the session are no longer valid).
A form can have fields that function like menu items. For more information see the explanation for the CHOICE display type (FIELD statement) in the section about Form Design Tool.