MENU TO
 Execute a lightbar menu for defined PROMPTs
------------------------------------------------------------------------------
 Syntax

     MENU TO <idVar>

 Arguments

     <idVar> is the name of the variable to be assigned 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.

 Description

     MENU TO is the selection mechanism for the CA-Clipper lightbar 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 <idVar> does exist, its initial
     value determines the first menu item highlighted.

 Notes

     .  Color: Menu items are painted in the current standard color
        with the highlighted menu item appearing in the current enhanced
        color.

     .  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 Up arrow from the first menu item
        moves the highlight to the last menu item.  Also, a Down arrow from
        the last menu item moves the highlight to the first.

        To make a selection, press Return or the first character of a menu
        item.  MENU TO then 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.  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.

        MENU TO Active Keys
        ---------------------------------------------------------------------
        Key            Action
        ---------------------------------------------------------------------
        Up arrow       Move to previous menu item
        Down arrow     Move to next menu item
        Home           Move to first menu item
        End            Move to last item menu item
        Left arrow     Move to previous menu item
        Right arrow    Move to next menu item
        PgUp           Select menu item, returning position
        PgDn           Select menu item, returning position
        Return         Select menu item, returning position
        Esc            Abort selection, returning zero
        First letter   Select first menu item with same first letter,
                       returning position
        ---------------------------------------------------------------------

 Examples

     .  This example creates a simple vertical lightbar 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"
        @ 7, 10 PROMPT "Edit" MESSAGE "Change Acct"
        @ 9, 10 PROMPT "Quit" MESSAGE "Return to DOS"
        MENU TO nChoice
        //
        DO CASE
        CASE nChoice = 0
           QUIT
        CASE nChoice = 1
           NewAccount()
        CASE nChoice = 2
           ChangeAccount()
        CASE nChoice = 3
           QUIT
        ENDCASE
        RETURN

 Files   Library is CLIPPER.LIB.