ETI menus

Determining the dimensions of menus

The simplest way to display a menu is to use stdscr as your default window and subwindow. Any titles, borders, or other decorative matter are displayed in the menu window; the menu proper is displayed in the menu subwindow. If you want to specify a menu window or subwindow, you use the functions set_menu_win or set_menu_sub. (These routines are treated in ``Associating windows and subwindows with menus''.) Whether or not you choose a menu window, ETI calculates the minimum window (or subwindow) size for your menu.

To determine the minimum window size for a menu, ETI considers five factors:

the size and number of items in a menu
whether option O_ROWMAJOR is on
whether option O_SHOWDESC is on
the format, or maximum number of rows and columns on a displayed page of the menu
the mark string for menu items

ETI knows the size and number of items in a menu as soon as you call new_menu, discussed above. By default, options O_ROWMAJOR and O_SHOWDESC are on. Option O_ROW_MAJOR ensures that the items are displayed in row major order -- fanning out left to right, then top to bottom. How to change this and other menu options is discussed in ``Setting and fetching menu options''. Option O_SHOWDESC ensures that an item's description, if any, is displayed with the item's name.

This section first describes the menu's format and mark string. It then describes the routine scale_menu, which uses the above information to set the window size for the menu.

NOTE: The five factors that determine the minimum window size have default values. You need not worry about them until you want to customize your menus.

Specifying the menu format

In general, the items comprising a menu do not fill a single screen. Sometimes they occupy considerably less space, sometimes considerably more. The following functions enable you to set the maximum number of rows and columns of menu items to be displayed at any one time.

SYNOPSIS

   int set_menu_format (menu, maxrows, maxcols)
   MENU  menu;
   int maxrows, maxcols;
   
   void menu_format (menu, maxrows, maxcols)
   MENU  menu;
   int  maxrows,  maxcols;

A menu page is the collection of currently visible items. Function set_menu_format establishes the maximum number of rows and columns of items that may be displayed on a menu page.

The actual number of rows and columns displayed may be less than maxrows or maxcols depending on the number of items and whether the O_ROWMAJOR option is on. (Menu options are described in ``Setting and fetching menu options''.) Function menu_format returns the maximum number of rows and columns of items that you set for the given menu.

The default number of item rows is 16, while the default number of item columns is one. If either maxrows or maxcols equals zero in the call to set_menu_format, the current value is not changed. An error occurs, however, if the value of either of these arguments is less than zero.

ETI calculates the total number of rows and columns in a row major menu as follows:

   #define minimum(a,b)	((a) < (b) ? (a) : (b))
   
   total_rows = (number_of_items - 1) / maxcols + 1;
   total_cols = minimum (number_of_items, maxcols);

ETI calculates the total number of rows and columns in a column major menu as follows:

   total_rows = (number_of_items - 1) /maxcols + 1;
   total_cols = (number_of_items - 1) /total_rows + 1;

Whether or not the O_ROW_MAJOR option is on, the number of rows and columns of items that are displayed at one time on a menu page is

   displayed_rows = minimum (total_rows, maxrows);
   displayed_cols = minimum (total_cols, maxcols);

If total_rows is greater than maxrows, the menu is scrollable -- your end-user can scroll up or down through the menu by making the appropriate menu driver request. See ``ETI menu requests''.

As an example, consider the displays in ``Examples of menu format (2, 2)'' and ``Examples of menu format (3, 2)''. They portray menus consisting of five items. The numbers 0 through 4 signify menu items in the order in which they live in the item pointer array. ``Examples of menu format (2, 2)'' shows the menu displayed with a format of maximum number of rows two, maximum number of columns two. To stipulate this format for menu m, you write

   set_menu_format(m,2,2);

Using the formulas above, we see that total_rows is 3 and total_cols is 2 in all four cases displayed in the two figures. The first display in each figure shows the menu in row major format (O_ROW_MAJOR on), the second in column major format. The displayed number of rows and columns in ``Examples of menu format (2, 2)'' is 2. To see the last row of items, your user can make the REQ_SCR_DLINE request to scroll down. If, instead, you set the format of this menu to three rows, two columns, you get one of the two displays in ``Examples of menu format (3, 2)''. The enclosing block in each case indicates the items displayed at one time.

   +---------+           +---------+
   | 0     1 |           | 0     3 |
   | 2     3 |           | 1     4 |
   +---------+           +---------+
     4                     2
   
    Row major             Column major
   

             Maximum rows 2

Examples of menu format (2, 2)

   +---------+           +---------+
   | 0     1 |           | 0     3 |
   | 2     3 |           | 1     4 |
   | 4       |           | 2       |
   +---------+           +---------+
   
    Row major             Column major
   

             Maximum rows 3

Examples of menu format (3, 2)

For a larger example, consider ``Examples of menu format (4, 3)''. Here the number of items is 18 and the format in both cases is four rows, three columns. In both cases, the total number of rows comes to six, the total number of columns to three, and the displayed number of rows to four. Calculation shows that changing the number of items in this example to 19 changes the number of rows to seven.

   +---------------+             +---------------+
   | 0     1     2 |             | 0     6    12 |
   | 3     4     5 |             | 1     7    13 |
   | 6     7     8 |             | 2     8    14 |
   | 9    10    11 |             | 3     9    15 |
   +---------------+             +---------------+
    12    13    14                 4    10    16
    15    16    17                 5    11    17
   
    Row major                     Column major

Examples of menu format (4, 3)

The column major examples emphasize that when the total number of rows is greater than the maximum number of rows, the items displayed do not exactly follow the order of the items in the array of item pointers. The items are arranged in column-major format throughout the entire menu, not within each displayed page. This conception agrees with your user's ability to scroll through the menu.

If successful, function set_menu_format returns E_OK. If an error occurs, it returns one of the following:

E_SYSTEM_ERROR: system error
E_BAD_ARGUMENT: rows < 0 or cols < 0
E_POSTED: menu is posted

If function set_menu_format is passed a NULL menu pointer, it sets a new system default. Suppose, for instance, that you want to change the default maximum number of rows of items displayed to ten, and the default maximum number of columns displayed to three. You can write

   set_menu_format((MENU *)0,10,3);

The function set_menu_format resets the value of top_row to 0. See ``Fetching and changing the top row'', for details.

Finally, if function menu_format receives a NULL menu pointer, it returns the current default format.

Changing your menu's mark string

The mark string distinguishes

selected items in a multi-valued menu
the current item in a single-valued menu.

The mark string appears just to the left of the item name.

SYNOPSIS

   int set_menu_mark (menu, mark)
   MENU  menu;
   char  mark;
   
   char  menu_mark (menu)
   MENU  menu;

Function set_menu_mark sets the mark string, while menu_mark returns the string. The initial default mark string is a minus sign (-). The mark string may be as long as you want, provided each item fits on one line of the menu's subwindow.

NOTE: Do not change the mark string area as long as you want that mark because ETI does not copy it.

You can call set_menu_mark either before or after the menu is posted. (See ``Posting and unposting menus''.) However, there is a restriction to calling it afterwards.

NOTE: If you call set_menu_mark with a posted menu, the length of the mark string must stay the same.

If the menu is posted and the length of the mark string changes, the function returns E_BAD_ARGUMENT and leaves the mark unchanged.

To change the mark string for menu m to ---> you can write

   MENU * m;
   
   set_menu_mark (m, "--->");
   		/* change mark string for menu m */

If successful, function set_menu_mark returns E_OK. If an error occurs, function set_menu_mark returns one of the following:

E_SYSTEM_ERROR: system error
E_BAD_ARGUMENT: menu is posted: change in string length impossible or string is NULL

Note that you can change the current default mark string for all subsequently created menus in your program by passing set_menu_mark a NULL menu pointer. To change the current default mark string to ---> you write

   set_menu_mark ((MENU *) 0, "--->");
   		/* change default mark string */

All subsequently created menus will have ---> as their mark string. To return the current default mark string, you call menu_mark with NULL:

   char * mark = menu_mark ((MENU *) 0);
   		/* default mark string */

Querying the menu dimensions

Remember that the size of menu items, the O_ROWMAJOR menu option, the menu format, and the menu mark determine the smallest window size for a menu. Function scale_menu returns this smallest window size in terms of the number of character rows and columns.

SYNOPSIS

   int scale_menu (menu, rows, cols)
   MENU  menu;
   int  rows, * cols;

Because function scale_menu must return more than one value (namely, the minimum number of rows and columns for the menu) and C passes parameters ``by value'' only, the arguments of scale_menu are pointers. The pointer arguments rows and cols point to locations used to return the minimum number of rows and columns for displaying the menu.

NOTE: You should call scale_menu only after the menu's items have been connected to the menu using new_menu or set_menu_items.

The following code places the minimal number of rows and columns necessary for menu m in rows and cols:

   MENU *m;
   int rows, cols;
   
   scale_menu (m, &rows, &cols);
   		/* return dimensions of menu m */

You use the values returned from scale_menu to create menu windows and subwindows. In the next section, we will see how to do this.

If successful, scale_menu returns E_OK. If an error occurs, the function returns one of the following:

E_SYSTEM_ERROR: system error
E_BAD_ARGUMENT: NULL menu pointer
E_NOT_CONNECTED: no connected items