menu_driver

menu_driver(3X)						      menu_driver(3X)



NAME
       menu_driver - command-processing loop of the menu system

SYNOPSIS
       #include <menu.h>
       int menu_driver(MENU *menu, int c);

DESCRIPTION
       Once  a	menu  has  been	 posted	 (displayed), you should funnel input
       events to it through menu_driver.  This routine has three major	input
       cases; either the input is a menu navigation request, it’s a printable
       ASCII character or it is the KEY_MOUSE special key associated with  an
       mouse event.  The menu driver requests are as follows:

       REQ_LEFT_ITEM
	    Move left to an item.

       REQ_RIGHT_ITEM
	    Move right to an item.

       REQ_UP_ITEM
	    Move up to an item.

       REQ_DOWN_ITEM
	    Move down to an item.

       REQ_SCR_ULINE
	    Scroll up a line.

       REQ_SCR_DLINE
	    Scroll down a line.

       REQ_SCR_DPAGE
	    Scroll down a page.

       REQ_SCR_UPAGE
	    Scroll up a page.

       REQ_FIRST_ITEM
	    Move to the first item.

       REQ_LAST_ITEM
	    Move to the last item.

       REQ_NEXT_ITEM
	    Move to the next item.

       REQ_PREV_ITEM
	    Move to the previous item.

       REQ_TOGGLE_ITEM
	    Select/deselect an item.

       REQ_CLEAR_PATTERN
	    Clear the menu pattern buffer.

       REQ_BACK_PATTERN
	    Delete the previous character from the pattern buffer.

       REQ_NEXT_MATCH
	    Move to the next item matching the pattern match.

       REQ_PREV_MATCH
	    Move to the previous item matching the pattern match.

       If  the	second	argument  is  a	 printable  ASCII character, the code
       appends it to the pattern buffer and attempts to move to the next item
       matching	 the  new  pattern.   If  there is no such match, menu_driver
       returns E_NO_MATCH and deletes the appended character from the buffer.

       If  the	second argument is one of the above pre-defined requests, the
       corresponding action is performed.

       If the second argument is the KEY_MOUSE special	key,  the  associated
       mouse  event is translated into one of the above pre-defined requests.
       Currently only clicks in the user window (e.g. inside the menu display
       area  or	 the  decoration  window) are handled. If you click above the
       display region of the menu, a REQ_SCR_ULINE is generated, if you	 dou-
       bleclick	 a  REQ_SCR_UPAGE  is  generated  and  if  you	tripleclick a
       REQ_FIRST_ITEM is generated. If you click below the display region  of
       the   menu,  a  REQ_SCR_DLINE  is  generated,  if  you  doubleclick  a
       REQ_SCR_DPAGE is generated and if you tripleclick a  REQ_LAST_ITEM  is
       generated.  If  you  click  at  an item inside the display area of the
       menu, the menu cursor is positioned to that item. If you	 double-click
       at  an  item  a	REQ_TOGGLE_ITEM is generated and E_UNKNOWN_COMMAND is
       returned. This return value makes sense, because a double  click	 usu-
       ally  means  that  an  item-specific  action  should be returned. It’s
       exactly the purpose of this return value to signal that an application
       specific	 command  should be executed. If a translation into a request
       was done, menu_driver returns the result	 of  this  request.   If  you
       clicked	outside the user window or the mouse event couldn’t be trans-
       lated into a menu request an E_REQUEST_DENIED is returned.

       If the second argument is neither printable ASCII nor one of the above
       pre-defined  menu  requests  or	KEY_MOUSE, the drive assumes it is an
       application-specific command and returns E_UNKNOWN_COMMAND.   Applica-
       tion-defined  commands  should be defined relative to MAX_COMMAND, the
       maximum value of these pre-defined requests.

RETURN VALUE
       menu_driver return one of the following error codes:

       E_OK The routine succeeded.

       E_SYSTEM_ERROR
	    System error occurred (see errno).

       E_BAD_ARGUMENT
	    Routine detected an incorrect or out-of-range argument.

       E_BAD_STATE
	    Routine was called from an initialization  or  termination	func-
	    tion.

       E_NOT_POSTED
	    The menu has not been posted.

       E_UNKNOWN_COMMAND
	    The menu driver code saw an unknown request code.

       E_NO_MATCH
	    Character failed to match.

       E_REQUEST_DENIED
	    The menu driver could not process the request.

SEE ALSO
       curses(3X), menu(3X).

NOTES
       The  header  file  <menu.h>  automatically  includes  the header files
       <curses.h>.

PORTABILITY
       These routines emulate the System V menu library.  They were not	 sup-
       ported  on  Version 7 or BSD versions. The support for mouse events is
       ncurses specific.

AUTHORS
       Juergen Pfeifer.	 Manual pages and adaptation for new curses  by	 Eric
       S. Raymond.



							      menu_driver(3X)