ETI menus

Establishing item and menu initialization and termination routines

Sometimes, you may want the menu driver to execute a specific routine during the change of an item or menu. The following functions let you do this easily.

SYNOPSIS

   typedef void (PTF_void) ();
   
   int set_menu_init (menu, func)
   MENU  menu;
   PTF_void func;
   

   PTF_void menu_init (menu)
   MENU  menu;
   

   int set_menu_term (menu, func)
   MENU  menu;
   PTF_void func;
   

   PTF_void menu_term (menu)
   MENU  menu;
   

   int set_item_init (menu, func)
   MENU  menu;
   PTF_void func;
   

   PTF_void item_init (menu)
   MENU  menu;
   

   int set_item_term (menu, func)
   MENU  menu;
   PTF_void func;
   

   PTF_void item_term (menu)
   MENU  menu;

The argument func is a pointer to the specific function you want executed by the menu driver. This application-defined function takes a menu pointer as an argument.

If you want your application to execute an application-defined function at one of the initialization or termination points listed below, you should call the appropriate set_ routine at the start of your program. If you do not want a specific function executed in these cases, you may refrain from calling these routines altogether.

The following subsections summarize when each initialization and termination routine is executed.

Function set_menu_init

The argument func to this function is automatically called by the menu system

just before the menu is posted
just after each menu scrolling operation, that is, every time the top row changes on a posted menu, whether by the menu driver in response to a request or by a program's call to set_current_item or top_row

Function set_item_init

The argument func is automatically called by the menu system

just before the menu is posted
just after the current item on a posted menu is changed, whether by the menu driver's response to a request or by a program's call to set_current_item or top_row

Function set_item_term

The argument func is automatically called by the menu system

just before the current item changes on a posted menu
just before the menu is unposted

Function set_menu_term

The argument func is automatically called by the menu system

just before a scrolling operation on a posted menu
just before the menu is unposted

If functions set_menu_init, set_menu_term, set_item_init, or set_item_term encounter an error, they return

E_SYSTEM_ERROR: system error

``Using an initialization routine to generate item prompts'' shows how you can use function set_item_init to implement a menu prompting feature as your end-user moves from item to item.

   WINDOW * prompt_window;
   
   void display_prompt (s)
   char * s;
   {
   	WINDOW * w = prompt_window;
   

   	werase (w);
   	wmove (w, 0, 0);           /* move to window origin */
   	waddstr (w, s);           /* write prompt in window */
   	wrefresh (w);             /* display prompt */
   }
   void generate_prompt (m)
   MENU * m;
   {
   

   	/* display the prompt string associated with the current item */
   

   	char * s = item_userptr (current_item (m));
   	display_prompt (s);
   }
   ITEM * items[NUMBER_OF_ITEMS + 1];
   

   main ()
   {
   	MENU * m;
   

   	for (i = 0; i < NUMBER_OF_ITEMS; ++i)
   	{
   

   		/* read in name and prompt strings here */
   

   		items[i] = new_item (name, "");
   		set_item_userptr (items[i], prompt);
   	}
   	items[i] = (ITEM *) 0;
   

   	m = new_menu (items);
   	set_item_init (m, generate_prompt);  /* set initialization routine */
   }

Using an initialization routine to generate item prompts

Function set_item_init arranges to call generate_prompt whenever the menu item changes. Function generate_prompt fetches the item user pointer associated with the current item and calls display_prompt, which displays the item prompt. Function display_prompt is a separate function to enable you to use it for other prompts as well.