Click above to get retro games delivered to your door ever month!

 menu to             Activate a menu initialized by prompt commands
------------------------------------------------------------------------------
 Syntax
   menu to uVar [on select do xProc] [save]

 Arguments
   uVar is a uint variable receiving the menu selection.
   xProc is a procedure to execute while navigating the menu.

 Description
   The menu to command activates a menu initialized by the @ prompt command.

   menu to activates a menu that has been previously defined by the
   @ prompt command. The menu to command takes keyboard input from the
   user and moves the highlight bar until the user presses enter, escape or
   the first significant character of a @ prompt menu item (i.e.
   leading spaces are ignored).

   Each time an arrow key is pressed, the highlight bar is positioned over
   the appropriate selection pad, the prompt message is displayed at the
   line specified by the set message to command and the procedure specified
   by on select do is executed.

   When the menu is invoked, the cursor bar is placed at the first
   @ prompt selection. If a key other than a cursor movement key is
   pressed, the menu to command checks for matches between the key and the
   first character of any menu prompt. If a match is found, the highlight
   bar is placed at the first item that matches the selection, and the
   command terminates with uVar set to the selected value. (Note that
   the match is not case-sensitive). If the enter key is pressed, the command
   terminates with uVar set to the value of the current selection.

   The up or left arrow keys move the cursor bar to the previous entry. The
   right or down keys move the cursor to the next entry. The home key places
   the cursor at the first entry. The end key places the cursor at the last
   entry.

   If the escape key is pressed, the command terminates with uVar set
   to the value of the current selection.

   menu to can be used in conjunction with the lastkey() function to
   implement menu accelerator keys. Menus can be vertical or horizontal as
   determined by the coordinates of the prompt selection pads.

   Instead of selecting a menu item by typing in the first significant
   character of an item, it is possible to define a hot key at any position
   in the items. This is done by placing an ampersand (&) character in front
   of the hot key character in the prompt string.

   When the menu gets displayed, hot keys are shown with the attributes
   defined in __syscolor[ CLR_UNSEL_CH ] or in __syscolor[ CLR_SEL_CH ],
   depending on the current state of an item (selected or un-selected).

   Note that hot keys are not case-sensitive.

   If an item does not contain a hot key, it still can be selected by its
   first significant letter. In this case, the first letter is automatically highlighted as hot key

   If the on select do clause is specified, the xProc function is called
   every time the selection bar moves to another valid menu entry.

   The on select do procedure is called with one parameter: the id of the
   selection pad highlighted by the last positioning key pressed. Because
   the on select do procedure is called every time a selection is
   highlighted, the select routine can be used to implement more advanced
   menu strategies.

   The @ prompt message is displayed before the on select do routine is
   executed.

   If the optional save subcommand is used in the menu to command,
   @ prompts are not cleared upon termination of the menu to command. To
   clear @ prompts, use the clear menu command.

 Example
   #define EXAMPLE_MENU
   #include example.hdr

   // Implement a simple menu
   
   proc Menu1
   vardef
      uint uChoice
   enddef
   @ 1,  0 prompt "Add"
   @ 1, 10 prompt "Edit"
   @ 1, 20 prompt "Quit"
   menu to uChoice
   if lastkey() != K_ESC
      @ 3, 0 ?? "Selection was", istr( uChoice )
   else
      @ 3, 0 ?? "Selection cancelled"
   endif
   wait
   endproc
   
   /*
   Implement a simple menu with hot keys.
   
   Use on select do to print a "help box" as the menu is being navigated by
   user. The parameter "selection_pad" is passed to "help_box" by the
   menu to command. It contains the id of the current prompt.
   */
   
   proc MenuHelp static
   param value uint nId
   @ 5, 3 ?? "Item", istr( nId )
   endproc
   
   proc Menu2
   vardef
      uint uChoice
   enddef
   __syscolor[ CLR_UNSEL_CH ] := BLACK_YELLOW
   __syscolor[ CLR_SEL_CH ]   := WHITE_YELLOW
   @ 1, 3 prompt " &Add  "
   @ 2, 3 prompt " &Edit "
   @ 3, 3 prompt " E&xit "
   menu to uChoice on select do MenuHelp
   @ 5, 0 ?? "Selection was", istr( uChoice )
   wait
   endproc
   
   proc Test_menuto
   cursor( .f. )
   clear
   Menu1()
   clear
   Menu2()
   endproc

   proc main
   Test_menuto()
   endproc