|
|
Normally, to create a menu, you must first create the items comprising it. To create a menu item, you use function new_item.
SYNOPSIS
ITEM new_item (name, description) char name; char description;Function new_item creates a new item by allocating space for the new item and initializing it. ETI displays the string name when the menu is later posted, but calling new_item does not alone connect the item to a menu. The item name is also used in pattern-matching operations. If name is NULL or the null string, then new_item returns NULL to indicate an error.
The argument description is a descriptive string associated with the item. It may or may not be displayed depending on the O_SHOWDESC option, which you can turn on or off with the set_menu_opts and related functions described below. If description is NULL or the null string, no description is associated with the menu item.
If successful, new_item returns a pointer to the new item. This pointer is the key to working with all item routines. When you pass it to them, it enables the menu subsystem to change, record, and examine the item's attributes.
If there is insufficient memory for the item, or name is NULL or the null string, then new_item returns NULL.
In general, you use an array to store the item pointers returned by new_item. ``Creating an array of items'' shows how you might create an item array of the planets of our solar system.
ITEM * planets[10];planets[0] = new_item ("Mercury", "The first planet"); planets[1] = new_item ("Venus", "The second planet"); planets[2] = new_item ("Earth", "The third planet"); planets[3] = new_item ("Mars", "The forth planet"); planets[4] = new_item ("Jupiter", "The fifth planet"); planets[5] = new_item ("Saturn", "The sixth planet"); planets[6] = new_item ("Uranus", "The seventh planet"); planets[7] = new_item ("Neptune", "The eighth planet"); planets[8] = new_item ("Pluto", "The ninth planet"); planets[9] = (ITEM *) 0;
Creating an array of items
Function new_item does not copy the name or description strings themselves, but saves the pointers to them. So once you call new_item, you should not change the strings until you call free_item.
SYNOPSIS
free_item(item) ITEM item;Function free_item frees an item. It does not, however, deallocate the space for the item's name or description.
The argument to free_item is a pointer previously obtained from new_item.
Once an item is freed, you must not use it again. If a freed item's pointer is passed to an ETI routine, undefined results will occur.
If successful, free_item returns
E_OK
.
If it encounters an error, it returns one of the following: