Creating and freeing menu items

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;

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;

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:

E_SYSTEM_ERROR

system error

E_BAD_ARGUMENT

null item

E_CONNECTED

item is connected to a menu