ETI menus

Posting and unposting menus

To post a menu is to write it on the menu's subwindow. To unpost a menu is to erase it from the menu's subwindow, but not destroy its internal data structure. ETI provides two routines for these actions.

SYNOPSIS

   int post_menu (menu)
   MENU  menu;
   
   int unpost_menu (menu)
   MENU  menu;

Note that neither of these functions actually change what is displayed on the terminal. After posting or unposting a menu, you must call wrefresh (or its equivalents, wnoutrefresh and doupdate) to do so.

If function post_menu encounters an error, it returns one of the following:

E_SYSTEM_ERROR: system error
E_BAD_ARGUMENT: NULL menu pointer
E_POSTED: menu is already posted
E_NOT_CONNECTED: no connected items
E_NO_ROOM: menu does not fit in subwindow

Regarding E_NO_ROOM, recall from ``Querying the menu dimensions'' that function scale_menu returns the number of rows and columns necessary to display the menu. It does not, however, know the size of the subwindow you are associating with the menu. Only when the menu is posted is this point checked. Any failure of the menu to fit in the subwindow is then detected.

If function unpost_menu executes successfully, it returns E_OK. In the following situations, it fails and returns the indicated values:

E_SYSTEM_ERROR: system error
E_BAD_ARGUMENT: NULL menu pointer
E_NOT_POSTED: menu is not posted
E_BAD_STATE: called from init or term

You might, for instance, receive E_NOT_POSTED if you forgot to post the menu in the first place or you mistakenly tried to unpost it twice.

``Sample routines displaying and erasing menus'' illustrates two routines you might write to post and unpost menus. Function display_menu creates the window and subwindow for the menu and posts it. Function erase_menu unposts the menu and erases its associated window and subwindow.

   static void display_menu (m)	/* create menu windows and post */
   MENU * m;
   {
   	WINDOW *	w;
   	int	rows;
   	int	cols;
   
   	scale_menu (m, &rows, &cols);	/* get dimensions of menu */
   

   		/* create menu window, subwindow, and border */
   

   	if (w = newwin (rows+2, cols+2, 0, 0)) {
   

   		set_menu_win (m, w);
   		set_menu_sub (m, derwin (w, rows, cols, 1, 1));
   		box (w, 0, 0);    /* create border of 0's */
   	     	keypad (w, 1);    /* set for each data entry window */
   	}
   	else
   		error ("error return from newwin", NULL);
   

   		/* post menu */
   

   	if (post_menu (m) != E_OK)
   		error ("error return from post_menu", NULL);
   	else
   	 	wrefresh (w);
   }
   

   static void erase_menu (m)     /* unpost and delete menu windows */
   MENU * m;
   {
   	WINDOW * w = menu_win (m);
   	WINDOW * s = menu_sub (m);
   

   	unpost_menu (m);       /* unpost menu */
   	werase (w);            /* erase menu window */
   	wrefresh (w);          /* refresh screen */
   	delwin (s);            /* delete menu windows */
   	delwin (w);
   }

Sample routines displaying and erasing menus

Function keypad is called with a second argument of 1 to enable virtual keys KEY_LL, KEY_LEFT, and others to be properly interpreted in the routine get_request described in ``Menu driver processing''. See the discussion of keypad in the curses(3ocurses) manual pages for details. Finally, note the placement of checks for error returns in this example.