menudriver(3X) menudriver(3X)

NAME
       mmeennuuddrriivveerr - command-processing loop of the menu system

SYNOPSIS
       ##iinncclluuddee <>
       int menudriver(MENU *menu, int c);

DESCRIPTION
       Once a menu has been posted (displayed), you should funnel input events
       to it through mmeennuuddrriivveerr.  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 KEYMOUSE special key associated with  an  mouse
       event.  The menu driver requests are as follows:

       REQLEFTITEM
            Move left to an item.

       REQRIGHTITEM
            Move right to an item.

       REQUPITEM
            Move up to an item.

       REQDOWNITEM
            Move down to an item.

       REQSCRULINE
            Scroll up a line.

       REQSCRDLINE
            Scroll down a line.

       REQSCRDPAGE
            Scroll down a page.

       REQSCRUPAGE
            Scroll up a page.

       REQFIRSTITEM
            Move to the first item.

       REQLASTITEM
            Move to the last item.

       REQNEXTITEM
            Move to the next item.

       REQPREVITEM
            Move to the previous item.

       REQTOGGLEITEM
            Select/deselect an item.

       REQCLEARPATTERN
            Clear the menu pattern buffer.

       REQBACKPATTERN
            Delete the previous character from the pattern buffer.

       REQNEXTMATCH
            Move to the next item matching the pattern match.

       REQPREVMATCH
            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, mmeennuuddrriivveerr returns
       EENNOOMMAATTCCHH 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 KEYMOUSE 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 dis-
       play  region  of  the  menu,  a REQSCRULINE is generated, if you dou-
       bleclick  a  REQSCRUPAGE  is  generated  and  if  you  tripleclick  a
       REQFIRSTITEM  is  generated. If you click below the display region of
       the  menu,  a  REQSCRDLINE  is  generated,  if  you   doubleclick   a
       REQSCRDPAGE  is  generated  and if you tripleclick a REQLASTITEM 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 REQTOGGLEITEM is generated and EEUUNNKKNNOOWWNNCCOOMMMMAANNDD is  returned.
       This  return  value  makes  sense, because a double click usually means
       that an item-specific action should be returned. It's exactly the  pur-
       pose  of  this return value to signal that an application specific com-
       mand should be executed. If a translation  into  a  request  was  done,
       mmeennuuddrriivveerr returns the result of this request.  If you clicked outside
       the user window or the mouse event couldn't be translated into  a  menu
       request an EERREEQQUUEESSTTDDEENNIIEEDD is returned.

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

RREETTUURRNN VVAALLUUEE
       mmeennuuddrriivveerr return one of the following error codes:

       EEOOKK The routine succeeded.

       EESSYYSSTTEEMMEERRRROORR
            System error occurred (see eerrrrnnoo).

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

       EEBBAADDSSTTAATTEE
            Routine was called from an initialization or termination function.

       EENNOOTTPPOOSSTTEEDD
            The menu has not been posted.

       EEUUNNKKNNOOWWNNCCOOMMMMAANNDD
            The menu driver code saw an unknown request code.

       EENNOOMMAATTCCHH
            Character failed to match.

       EERREEQQUUEESSTTDDEENNIIEEDD
            The menu driver could not process the request.

SEE ALSO
       ccuurrsseess(3X), mmeennuu(3X).

NNOOTTEESS
       The header  file  <>  automatically  includes  the  header  files
       <>.

PPOORRTTAABBIILLIITTYY
       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.



                                                               menudriver(3X)