MENU TO
 Execute a light-bar menu for defined PROMPTs.
------------------------------------------------------------------------------

 Syntax:

     MENU TO <idVar> [SAVE] [USING <nExp>] [WITH <xPassThrough>] [FORCE]

 Arguments:

     <idVar> is the name of the variable to assign the result of the
     menu selection.  If the specified variable is not visible or does not
     exist, a private variable is created and assigned the result.

     SAVE tells the MENU TO process not to distroy the PromptList
     array when it has exited.  This allows for a MENU TO to be activated
     within a loop.

     <nExp> is an optional numeric expression used to assign the initial
     menu item.  By default the initial menu item is initialized with <idVar>.
     (See LastMenu().)

     <xPassThrough> is an optional codeblock which gets evaluated when all
     of the keystroke checking has been completed and the keystroke was not
     utilized by the MENU TO process.  The intent of this codeblock is to
     pass additional behaviour into the MENU TO process.  <xPassThrough>
     must return a lgical whether it was able to use the event.  If a true
     is returned then the MENU TO process is terminated.

     FORCE causes the initial <idVar> within the MENU TO process to
     be executed on initialization.


 Description:

     MENU TO is the selection mechanism for the Clipper light-bar menu
     system.  Before invoking MENU TO, first define the menu items and
     associated MESSAGEs with a series of @...PROMPT commands.  Then,
     activate the menu with MENU TO <idVar>.  If <idVar> does not exist or
     is not visible, MENU TO creates it as a private variable and places the
     highlight on the first menu item.  If it does exist, its initial value
     determines the first menu item highlighted.

 Notes:

     .  Color: Menu items are painted in the current menu color with
        the highlighted menu item appearing in the enhanced color (see
        SetMenuColor()).

     .  Navigation and selection: Pressing the arrow keys moves the
        highlight to the next or previous menu item.  As each menu item is
        highlighted the associated MESSAGE displays on the row specified
        with SET MESSAGE.  If WRAP is ON, an Uparrow from the first menu
        item moves the highlight to the last menu item.  Likewise, a Dnarrow
        from the last menu item moves the highlight to the first.

        To make a selection, press Return or the highlighted ALT character
        of a menu item.  If an ACTION was present for the menu item, it will
        be executed, otherwise MENU TO returns the position of the selected
        menu item as a numeric value into the specified memory variable.
        Pressing Esc aborts the menu selection and returns zero if the
        SET ESCAPE is on.  The table below summarizes the active keys within
        MENU TO.

     .  SET KEY procedures: A MENU TO command can be nested within a SET
        KEY procedure invoked within a menu without clearing the pending
        PROMPTs providing LOCAL PromptList := {} has been issued at the top
        of the called procedure.

        Table 4-8: MENU TO Active Keys
        -------------------------------------------------------------------
        Key                Action
        -------------------------------------------------------------------
        Dnarrow            Activate associted pulldown (if applicable)
        Home               Move to first menu item
        End                Move to last item menu item
        Leftarrow          Move to previous menu item
        Rightarrow         Move to next menu item
        Return             Select menu item, returning position or actioning
        Esc                Abort selection, returning zero if SET ESCAPE
        ALT Letter         Select first menu item with same highlighted
                           first letter, returning position or actioning
        Letter             Select first menu item with same highlighted
                           first letter, returning position or actioning
                           providing the highlight bar is not in a PULLDOWN
                           or PULLOUT.
    -------------------------------------------------------------------

 Examples:

     This example creates a simple vertical light-bar menu with messages
     appearing centered on line 23.  When invoked, the highlight defaults to
     the second menu item based on the initial value of nChoice:

     LOCAL nChoice := 2
     SET WRAP ON
     SET MESSAGE TO 23 CENTER
     @ 6, 10 PROMPT "Add"  MESSAGE "New Acct" ACTION NewAccount()
     @ 7, 10 PROMPT "Edit" MESSAGE "Change Acct" ACTION ChangeAccount()
     @ 9, 10 PROMPT "Quit" MESSAGE "Return to DOS" ACTION FALSE
     MENU TO nChoice

     QUIT
     RETURN

     This examples displays a few prompts and demonstrates the use of the
     SAVE option on the MENU TO action.

     #INCLUDE "CUACLIP.CH"

     FUNCTION Main()

     LOCAL PromptList:={}
     LOCAL answer:=2
     LOCAL aPullDown := { ;
       { "~Save", "Save the file...", {|| SaveIt() }, {|| HasChanged() } },;
       { "Save ~As", "Save the file with a new name...", {|| SaveNew() }, ;
         {|| HasChanged() } }, ;
       { "~New", "Clear the data...", {|| ClearIt() }, {|| HasChanged() } },;
       { }, ;
       { "E~xit", "Exit and return to DOS..." }, {|| FALSE } }

     SET MESSAGE TO MAXROW() CENTER
     SET SCOREBOARD OFF
     SETCOLOR("W+/B,B/W,,,W/B")
     SetMenuColor("W/B,B/W,N+/B,W+/B")
     SetMessColor("W/B")
     SETCURSOR(0)
     CLS

     ALTD(0)

     @ 0,1 PROMPT "~File" MESSAGE "Save, clear or exit..." ;
                     PULLDOWN aPullDown
     @ 0,1 PROMPT "~Add" MESSAGE "Add a record..." ;
                     WHEN !NextOne() ;
                     ACTION Demo( TRUE )
     @ 0,COL() + 2 PROMPT "~Edit" ;
                     MESSAGE "Edit a record..." ;
                     ACTION Demo()
     @ 0,COL() + 2 PROMPT "~Delete" ;
                     MESSAGE "Delete a record..." ;
                     WHEN NextOne();
                     ACTION TRUE
     @ 0,COL() + 2 PROMPT "~Next" ;
                     MESSAGE "Next..." ;
                     ACTION NextOne(!NextOne())
     @ 0,COL() + 2 PROMPT "~TBrowse" ;
                     MESSAGE "Try the TBrowse demo..." ;
                     ACTION TBDemo()

     MENU TO answer

     SETCURSOR(1)

     RETURN NIL


     STATIC FUNCTION NextOne( newvar )

     STATIC var := TRUE
     LOCAL oldVar := var

     IF PCOUNT() == 1
        var := newvar
     ENDIF

     RETURN oldVar


 Files:  Library is CUACLIP.LIB and the header file is CUACLIP.CH.