ETI menus

Setting and fetching menu options

ETI provides several menu options, some of which we have already met. Two functions manipulate options: one sets them, the other returns their settings.

SYNOPSIS

   int set_menu_opts (menu, opts)
   MENU  menu;
   OPTIONS opts;
   
   OPTIONS menu_opts (menu)
   MENU  menu;
   

   options:
   	O_ONEVALUE
   	O_SHOWDESC
   	O_ROWMAJOR
   	O_IGNORECASE
   	O_SHOWMATCH

Besides turning the named options on, function set_menu_opts turns off all other menu options. By default, all menu options are on.

The menu options and their effects are as follows:

O_ONEVALUE: determines whether the menu is a single-valued or multi-valued. In general, menus are single-valued and this option is on. Recall that upon exit from single-valued menus, your application queries the current item to ascertain the item selected. Turning off this option signifies a multi-valued menu. One way to select several items is to use the REQ_TOGGLE_ITEM request, another is to call set_item_value. (See ``Multi-valued menu selection request'' and ``Manipulating an item's select value in a multi-valued menu''.) Recall that your application must examine each item's select value to determine whether it has been selected. When this option is on, all item select values are FALSE.
O_SHOWDESC: determines whether or not the description of an item is displayed. By default, this option is on and both the item name and description are displayed. If this option is off, only the name is displayed.
O_ROWMAJOR: determines how the menu items are presented on the screen -- in row-major or column-major order. In row-major order, menu items are displayed first left to right, then top to bottom. In column-major order, they are displayed first top to bottom, then left to right. By default, this option is on, so menu items are displayed in row-major order. If the option is off, the items are displayed in column-major order. See ``Specifying the menu format'', for more on how menus are displayed.
O_IGNORECASE: instructs the menu driver to ignore upper- and lower-case during the item match operation. If this option is off, character case is not ignored and the match must be exact.
O_SHOWMATCH: determines whether visual feedback is provided as each item's data entry is processed. Ordinarily, as soon as a match occurs, the cursor is advanced through the item to reflect the contents of the pattern buffer. If this option is off, however, the cursor remains to the left of the current item.

Like all ETI options, menu OPTIONS are Boolean values, so you use Boolean operators to turn them on or off with functions set_menu_opts and menu_opts. For example, to turn off option O_SHOWDESC for menu m0 and turn on the same option for menu m1, you can write:

   MENU * m0, * m1;
   
   set_menu_opts (m0, menu_opts (m0) & ~O_SHOWDESC);
   		/* turn option off */
   set_menu_opts (m1, menu_opts (m1) |  O_SHOWDESC);
   		/* turn option on  */

ETI provides two alternative functions for turning options on and off for a given menu.

SYNOPSIS

   int menu_opts_on (menu, opts)
   MENU  menu;
   OPTIONS opts;
   
   int menu_opts_off (menu, opts)
   MENU  menu;
   OPTIONS opts;

Unlike function set_menu_opts, these functions do not affect options that are unmentioned in their second argument. In addition, if you want to change one option, you need not apply Boolean operators or use menu_opts.

As an example, the following code turns option O_SHOWDESC off for menu m0 and on for menu m1:

   MENU * m0, * m1;
   
   menu_opts_off (m0, O_SHOWDESC); /* turn option off */
   menu_opts_on  (m1, O_SHOWDESC); /* turn option on  */

As usual, you can change the current default for each option by passing a NULL menu pointer. For instance, to turn the default option O_SHOWDESC off, you write

   menu_opts_off ((MENU *) 0, O_SHOWDESC);
   		/* turn default option off */

In general, functions set_menu_opts, menu_opts_on, and menu_opts_off return E_OK. If an error occurs, they return one of the following:

E_SYSTEM_ERROR: system error
E_POSTED: menu is posted