Revision as of 17:17, 18 March 2009

@...MENU

Class

Menus

Purpose

Define a menu option

Syntax

@<expN1>,<expN2> MENU <expC1>

[COMMAND <commands>]

[HELP <expC2>]

[HELPFILE <.hlp filename> | (<expC3>)]

[NOREFRESH]

[PULLDOWN <expC4> | @<program | procedure> WITH [<parameter-list>]

See Also

MENU, MENU(), MENU AT, MENU FIELDS, MENU FORMAT, MENU FRAME, MENU QUERY, MENU SCOPE, MENUITEM(), READ MENU, RESTORE MENU, SAVE MENU, SET MCONFIRM, SET POSTMENU, SET PREMENU

Description

The @...MENU command is used to create menus. This command defines the menu options that are activated with the MENU command. @…MENU menus can also be created in the Forms Designer, see the CREATE SCREEN command for full details.

Menus can be navigated using the cursor keys. Pulldown menus will be activated automatically as they are highlighted, unless SET MCONFIRM is ON. Menu items can be selected using the first character of the item, the item accelerator key or the [RETURN] key. If SET MCONFIRM is ON, then a menu must be highlighted using the cursor keys or accelerator, then selected using the [RETURN] key.

The MENU <expC1> clause defines the menu option that will be displayed at the specified row <expN1> and column <expN2> when the MENU command is executed. You may also use the character expression <expC1> to define horizontal lines, non-selectable items, and accelerator keys in menus. Horizontal lines are defined by specifying a backslash and a dash (-). Non-selectable items are defined by preceding the menu option with a backslash. Accelerator keys are highlighted letters in menu option text that select the option when pressed. To designate a letter as an accelerator key, precede the letter with a backslash and a "less than" sign (<). Recital menu options can always be selected by pressing the first letter of the option. Accelerator keys are an excellent way to illustrate that selection method, and to provide alternate keys when there are menu options beginning with the same first letter.

NOTE: When a menu is placed in user-defined window, the coordinates are relative to the window not to the screen.

COMMAND <commands>

The COMMAND <commands> clause specifies the commands to be executed if the particular menu option is selected when the menu is activated. Multiple commands can be used by separating each command with the ";" character. If no COMMAND option is specified, you will exit from the menu when a menu option is selected. If you want to exit from the menu and use an @...MENU COMMAND option, the EXIT keyword must be specified on the MENU command. Selection of any item from the menu will then exit the menu after execution of the specified COMMAND line, unless the NOEXIT keyword is included in the COMMAND line.

It should be noted that the COMMAND option in the MENU command can call another menu, which can in turn call another menu. By nesting MENU commands the Recital/4GL code can be written in a non-procedural way, since once the menu is exited, control will return automatically to the calling menu.

HELP <expC2>

A HELP message, associated with each menu option, can be displayed in the message line when the menu option is highlighted. The message <expC2>, is a text line (maximum 80 characters) which can include macro substitution of memory variables and function key substitution of legal control characters.

HELPFILE <.hlp filename> | (<expC3>)

The HELPFILE clause allows context sensitive help information to be displayed when the [HELP] key is pressed. The <.hlp filename> will be displayed in a read-only window for viewing when the [HELP] key is pressed. The file name can be substituted with a <expC3>, enclosed in round brackets, which returns a valid filename. The command, SET INSTRUCT, must be ON when using this option.

NOREFRESH

By default, when returning from executing the command(s) specified for the menu option, the current menu is refreshed on the screen. The NOREFRESH keyword disables this.

PULLDOWN <expC4> | @<program | procedure> WITH [<parameter-list>]

Pulldown and pullright menus can be invoked in Recital/4GL programs by using the PULLDOWN option of the @...MENU command and the PULLRIGHT option of the MENU command respectively. The PULLDOWN <expC4> refers to a list of items that will appear in the pulldown menu upon placing the cursor on the associated menu item. The items are defined in a comma-separated character string.

If a text item is selected (i.e. by pressing [RETURN] while the item is highlighted) the MENUITEM() and MENU() functions can be used in the command line to allow processing to continue based on the item that was selected.

The PULLDOWN <program | procedure> WITH <parameter-list> option will cause execution of a command procedure or function and pass parameters to it when the cursor is placed on the menu item. In this option, <program | procedure> is any procedure or function name and <parameter-list> is a list of parameters separated by commas that will be passed to the <program | procedure>. The <program | parameter> can include expressions, so that if you pass MENUITEM() or MENU() as a parameter to a procedure, processing can proceed selectively based on the menu item chosen.

The @...MENU command also supports FoxBASE+ style menus, in which case the full syntax is as shown below:

@ <row>, <col> MENU <array name>,<nitems> [,<scroll size>]; [TITLE <expC>]

This FoxBASE+ command cannot be used in conjunction with any of Recital's @...MENU commands. The READ MENU command is used to activate the FoxBASE+ @...MENU command.

Example

@0,0 menu "Exit";
help "Exit from the system."
@0,5 menu "Browse";
help "Browse the table.";command "Browse; clear"
@0,12 menu "Append";
help "Append a new record.";command "append"
menu

Products

Recital Mirage Server, Recital Terminal Developer