ETI menus

Creating and freeing menus

Once you create the items for your menu, you can create the menu itself. To create and initialize a menu, you use function new_menu.

SYNOPSIS

   MENU  new_menu (items)
   ITEM  items;

The argument to new_menu is a NULL-terminated, ordered array of ITEM pointers. These pointers define the items on the menu. Their order determines the order in which the items are visited during menu driver processing, described below.

Function new_menu does not copy the array of item pointers. Instead, it saves the pointer to the array for future use.

NOTE: Once your application program has called new_menu, it should not change the array of item pointers until the menu is freed by free_menu or the item array is replaced by set_menu_items, described below.

Items passed to new_menu are connected to the menu created. They cannot be simultaneously connected to another menu. To disconnect the items from a menu, you can use function free_menu or function set_menu_items, which changes the items connected to a menu from one set to another. See ``Fetching and changing menu items''.

If successful, new_menu returns a pointer to the new menu. The following error conditions hold:

If there is insufficient memory for the menu or it detects an item connected to another menu, new_menu returns NULL.
If the array of item pointers is not NULL-terminated, undefined results occur.

In addition, if new_menu's argument items is NULL, as in

   MENU * m;
   
   m = new_menu ((MENU *) 0);

it creates the menu with no items connected to it and assigns the menu pointer to m.

The menu pointer returned by new_menu is the key to working with all menu routines. You pass it to the appropriate menu routine to do such tasks as post menus, call the menu driver, set the current item, and record or examine menu attributes.

Turn again to ``Sample menu program to create a menu in ETI'' for an example showing how to create a menu. In general, you want to use a while loop as illustrated to create the menu items and assign the item pointers to the item pointer array. Note the NULL terminator assigned to the item pointer array before the menu is created with new_menu

When you no longer need a menu, you should free the space allocated for it. To do this, you use function free_menu.

SYNOPSIS

   int free_menu (menu)
   MENU  menu;

Function free_menu takes as its argument a menu pointer previously obtained from new_menu. It disconnects all items from the menu and frees the space allocated for the menu. The items associated with the menu are not freed, however, because you may want to connect them to another menu. If not, you can free them by calling free_item.

Remember that once a menu is freed, you must not pass its menu pointer to another routine. If you do, undefined results occur.

If successful, calls to free_menu return E_OK. If free_menu encounters an error, it returns one of the following:

E_BAD_ARGUMENT: NULL menu pointer
E_POSTED: menu is posted
E_SYSTEM_ERROR: system error

For E_POSTED, see ``Posting and unposting menus''.