USERMENU Instruction

USERMENU( options ) pairs of id_number>>"menustring"

USERMENU allows you to add one or more user-defined menus to the RATS menu bar. Once a USERMENU is activated, it controls the flow of program execution. No instructions will be executed until the user makes a selection from the menu(s).

This essentially replaces the MENU and CHOICE instructions, although they are still supported, and are useful in some situations. USERMENU is very useful for writing interactive procedures in RATS.

Parameters

id_num>>'menustring'

The parameter list specifies which menu items will be affected by the current USERMENU command. The id_numbers are integer values used to identify each menu item. For example, you might use 1, 2, 3 and 4, or 1000, 1001, 1002, and 1003 as id_numbers. The menustrings supply the corresponding names that will appear in the pull-down menu. They are required when you create the menu with ACTION=DEFINE, but are optional with ACTION=MODIFY.

When you define the menu, the parameter list must include all of the menu items you want in the menu. You cannot add or remove menu items after you have defined the menu.

With the ACTION=MODIFY option, the parameters specify the menu items you wish to modify. Use this to change the name of the item(s) (by supplying a different menustring), to enable or disable, and check or uncheck items.

All menu items must have a unique id_num, even if you are doing multiple USERMENU’s. See the section on “Using Multiple USERMENU’s” for more information.

Options

ID=menu identification number [0]

If you want to use two or more USERMENU’s simultaneously, you must use the ID option with ACTION=DEFINE to assign a unique, non-zero integer identification number to the USERMENU being defined. You can then use that number to refer to the menu in later operations. Do not use the ID option when working with only one menu. See “Using Multiple USERMENU’s” below.

ACTION=DEFINE/MODIFY/[RUN]/REMOVE

Use ACTION=DEFINE to define a menu, set its menu bar title, and the list of menu items. This is the first step. Note that the menu does not go into the menu bar until you do ACTION=RUN. This gives you time to modify its appearance after the initial definition.

Use ACTION=MODIFY to change the appearance or titles of items within a menu. See the ENABLE and CHECK options below.

ACTION=RUN actually adds your menu(s) to the menu bar (if they are not already there) and suspends the execution of the program until the user makes a selection from a menu. Your menu is in (almost) complete control of the program. The user has access to the other menu bar operations, but can execute no other RATS instructions until you say so. You should provide some form of a quit or abort item in your menu to allow the user to get out when she is done. When the user has selected an item from a USERMENU menu, execution continues with the line following USERMENU(ACTION=RUN) instruction. The variable %MENUCHOICE is set to the id_number of the selected item.

ACTION=REMOVE removes the menu(s) from menu bar. It is your job to do this when you no longer need the menu(s).

TITLE="title string'"

The TITLE option sets the title of the menu as it will appear in the menu bar. Use this option with ACTION=DEFINE. You should keep this short (single word) so the menu bar does not get cluttered.

ENABLE=NO/YES

With ACTION=MODIFY, you can use ENABLE=YES to enable the specified menu item(s), or ENABLE=NO to disable them. Use ENABLE=NO to prevent the user of your program from selecting items which cannot be executed yet, possibly because other steps must be completed first. All items are enabled initially.

CHECK=NO/YES

Use CHECK=YES with ACTION=MODIFY to place “check marks” in front of the specified menu item(s), and CHECK=NO to remove them. You can use this to indicate to the user that a “switch” is off or on, or that a certain operation has been completed.

The %MENUCHOICE Variable

As noted above, when the user selects an operation from a USERMENU, RATS stores the id_number of the selected menu item in the reserved variable %MENUCHOICE. You can use conditional statements to check the value of %MENUCHOICE and then control program flow accordingly. See the example below for details.

Using Multiple USERMENU’s

RATS allows you to have several USERMENU’s active at one time. In general, these are handled just like single menus, except for the following:

•You define each menu with a separate USERMENU command. You must use the ID option to assign a unique non-zero id number to each menu.

•The ACTION=RUN option will always activate all currently defined menus, so you need to define all the menus before doing USERMENU(ACTION=RUN). The ID option is ignored with ACTION=RUN.

•By default, the ACTION=REMOVE option will remove all active menus from the menu bar. To remove only a particular menu, use the ID option along with ACTION=REMOVE.

•You must use unique menu item id_numbers for each menu item (that is, two menu items cannot have the same id_number, even if they appear on different menus).

Examples

The trivial example below creates a simple menu with three items. Selecting either of the first two items causes RATS to display a message in the output window. The third item closes the menu.

* Define a menu with three items:

usermenu(action=define,title="Test") $

1>>"First item" 2>>"Second item" 3>>"Quit menu"

* Begin loop

loop

* Activate menu:

usermenu(action=run)

* Act on selection. If "Quit", close menu and break out of loop:

if %menuchoice==1

display "First item was selected"

if %menuchoice==2

display "Second item was selected"

if %menuchoice==3

{

usermenu(action=remove)

break

}

end loop