|
|
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.
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:
MENU * m;it creates the menu with no items connected to it and assigns the menu pointer to m.m = new_menu ((MENU *) 0);
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_POSTED
,
see
``Posting and unposting menus''.