ETI menus

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.


   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.


   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.

NOTE: To free an item, you must have already created it with new_item and it must not be connected to a menu. If these conditions are not met, free_item returns one of the error values listed below.

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:

system error

null item

item is connected to a menu

Next topic: Two kinds of menus: single- or multi-valued
Previous topic: Sample menu program to create a menu in ETI

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004