ETI menus

Setting the item user pointer

For each item created, ETI automatically allocates a special user pointer that enables you to associate arbitrary data with the item. By default, the user pointer's value is NULL. You may set its value to whatever you want or not use it at all.

SYNOPSIS

   int set_item_userptr (item, userptr)
   ITEM  item;
   char  userptr;
   
   char  item_userptr (item)
   ITEM  item;

These two functions are helpful for creating item data such as title strings, help messages, and the like.

Any defined structure can be connected to an item using the item's user pointer. The pointer must be cast to (char *) and then later recast back to
(defined-struct *). ``Using an item user pointer'' shows how to use an item's user pointer with a struct ITEM_ID, which stores biological information.

   typedef struct
   {
   	int       id;
   	char *    name;
   	char *    type;
   }
   	ITEM_ID;
   
   ITEM_ID ids[7] =
   {
   	1, "apple", "fruit",
   	2, "ant", "insect",
   	3, "cow", "mammal",
   	4, "lizard", "reptile",
   	5, "potato", "vegetable",
   	6, "zebra", "mammal",
   	0, "", "",
   };
   

   ITEM * items[7];
   

   for (i = 0; ids[i]; ++i)
   {
   	items[i] = new_item (ids[i].name, ""); /* create item from each ids.name */
   

   	/* set user pointer to point to start of each struct in ids[] */
   

   	set_item_userptr (items[i], (char *) &ids[i]);
   }
   items[i] = (ITEM *) 0;

Using an item user pointer

Note that the pointer to each entry in array ids is cast to char *, which set_userptr requires. You might then write a function that uses function item_userptr to return the information. The following function returns the item type:

   char * get_type (i)
   ITEM * i;
   {
   	ITEM_ID * id = (ITEM_ID *) item_userptr (i);
   	return id -> type;
   }

Here the value returned by item_userptr is recast to ITEM_ID * so the item's type may be found.

Finally, you might call get_type to write the type, thus:

   WINDOW * win;
   
   waddstr (win,get_type(i));

If successful, set_item_userptr returns E_OK. Otherwise, it returns the following:

E_SYSTEM_ERROR: system error

If function set_item_userptr is passed a NULL item pointer, the argument userptr becomes the new default user pointer for all subsequently created items. As an example, the following sets the new default user pointer to point to the string You are Here:

   set_item_userptr( (ITEM *) 0, "You are Here");