menu(1)

menu -- menu/form interface generator

Synopsis

menu [-r] [-c] -f form-description-file -o output-file

Description

The menu command is a menu and form interface generator that creates full-screen forms and menus for accepting user input and for displaying information. The form or menu to be displayed is specified in a form description file containing all the text the user will see. By keeping all displayed text in a file external to the menu binary, menus and forms can be translated to other languages without changing the scripts that invoke menu. The output of the menu command is a file of shell variable assignment statements that can be used by a shell script.

The form description file consists of keywords, each denoting the start of a new section of text, and corresponding to a different part of the display. The text that follows a keyword can be hard-coded or it can be redirected from a file or a command.

The menu tool uses curses and the Extended Terminal Interface (ETI) to handle display and input. It is compiled with the libraries libform and libcurses. Most of the work of the tool is done by routines in these libraries; the bulk of the code in menu consists of parsing the form description file and creating the forms for these library routines.

There are three types of menus available with menu. The first type is the numbered menu, where the user is presented with a numbered list and is asked to select a number. The second is the form, where the user is presented with a multiple field form to fill out, and the third is an information screen, where the user may be required only to press <Enter> (or <Return>) to continue. See menu(4) for a complete explanation of these menu types.

The help facility

The menu command is equipped with a two-level help facility, with help for the menu or form specified in the form description file, and help on how to use a menu interface itself provided in a support file installed with the operating system.

Navigation

The menu command pre-defines the navigation keys for you and they cannot be redefined. In menus, a user can exit a numbered menu in either of two ways; first, by interrupting the execution with a SIGINTR (for example, by pressing <Del>); and second, by entering a valid number in the input field. If the user enters an invalid number, or makes some other typing mistake, an error bar is displayed on the screen. The user can then erase the field using <Bksp> and retype the value.

In forms, a user presses <Tab> to move to the next field or <Backtab> (<Shift><Tab>) to move to the previous field. For all types of fields except the TYPE_ENUM type, the input field is shown in inverse-video, When the cursor is positioned in a field, the user can type a value in the inverse-video area. In TYPE_ENUM fields, the first choice is already displayed in the field, in bright video. The user can cause the next choice to be displayed in the field. by pressing the left or right arrow key (or the <-> or <+> keys). The user can select the choice currently displayed, and move on to the next field, by pressing <Enter> or <Tab>.

When the form is filled out to the user's satisfaction, the user then presses <Tab> to move to the Apply Radio Button, and presses <Enter> to apply the choices filled out in the form fields. A user cannot exit from a form screen until the Apply button is ``pressed'' (or menu is interrupted).

After the form has been filled out, a user can reset the form to its state when first displayed by pressing <Tab> to move to the Reset Radio Button, and then pressing <Enter>.

In information screens, a user acknowledges having seen the screen and exits by pressing <Enter> (or <Return>).

Structure of form description files

Any menu, form, or information screen produced with the menu tool is an ETI form (see Character User Interface Programming for details). Each form is three pages (terminal screens) long. The first page is the menu, form, or information screen as specified in the form description file. It may contain titles, labels for other fields, help instructions, a form or menu, and many other fields.

The second page is the help screen for the form, as specified in the ``.help'' section of the form description file. Help screens simply display text -- additional information about the task at hand. It is entered by pressing either <F1> or <?>, and is exited by pressing <Esc>. A help screen may display more than one page of text; the following page can be viewed by pressing <PgDn> or <1>. and the previous page can be displayed by pressing <PgUp> or <2>. Thus, accessing help is really paging down on the form, and exiting help is really paging up on the form. The help pages are each a single field that may contain more text than can fit on the screen, and so each help screen, while one logical page of the form, may contain multiple pages of text to be displayed.

The third and last page is the help screen for the menu tool itself. This second level of help is built-in to the menu help facility, and provides additional information about navigating in and among the screens of a menu interface. Pressing <Esc> from the second level help facility puts the user back in the primary help screen.

Color

The curses library provides the colors for the menu tool. Given a color monitor the default colors are: regular menus, forms, and information screens are white text on a blue background; help screens appear in the default colors of black text on a cyan background; and error messages appear in the default colors of white text on a red background. Default colors can be overridden using environment variables, as described on the menu_colors.sh(1) manual page.

Operands

The options available are:

-c: This option clears the screen. No other option is read if -c is specified on the command line. It is useful if a form created with the -r option is displayed on the screen (see -r below).
-r: This option retains the form on the screen after input processing is complete, and displays a flashing ``Working...'' message at the bottom of the screen. If no input is required (that is, the screen is simply displaying
information), the form is displayed initially with a flashing ``Working...'' message at the bottom of the screen.
-f form-description-file: This file contains the description of the form to be displayed by menu. It contains all the text that will appear on the screen. With the exception of error messages sent to stdout, no text is generated from within menu. This is for ease of internationalization. This option is required unless the -c option is specified. menu will fail if form-description-file is not readable.
-o output-file: This file contains the output from the menu, which consists of shell statements of the form ``VARIABLE="value"'', reflecting the input entered in the menu by the user. This output file can be later read in by the shell script that called menu. This option is required unless the -c option is specified. menu will fail if output-file is not writable.

Files

/etc/inst/locale/C/menus/menu.errs: error strings produced by menu(1)

References

menu(4), menu_colors.sh(1)
Character User Interface Programming

Notices

menu(1) will be made obsolete and be replaced with other tools in a future release.