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

##############################################################################
###+---------+################################################################
#+-| MENU TO |---------------------------------------+########################
#| +---------+ The MENU TO command activates a menu  |########################
#|             initialized by the @...PROMPT command |########################
#+---------------------------------------------------+########################
##############################################################################
##############################################################################
#+--| Syntax |----------------------------------------------------------+#####
#|     MENU TO <Uint-var> [ON SELECT DO <Procedure>] [SAVE] [RETURN]    |#####
#+----------------------------------------------------------------------+#####
##############################################################################
##############################################################################
#######+---| Description |--------------------------------------------+#######
#######| 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 character of a       |#######
#######| @...PROMPT menu item.                                        |#######
#######| ------------------------------------------------------------ |#######
#######| 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 <Uint-var> set to the selected value.  If    |#######
#######| the enter key is pressed, the command terminates with <Uint- |#######
#######| var> 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    |#######
#######| <Uint-var> 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.                                   |#######
#######| ------------------------------------------------------------ |#######
#######| ON SELECT DO <Procedure>                                     |#######
#######|                                                              |#######
#######| If specified, the ON SELECT DO <Procedure> 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.                                         |#######
#######| ------------------------------------------------------------ |#######
#######| RETURN                                                       |#######
#######|                                                              |#######
#######| The keyword RETURN initiates the menu system at a menu       |#######
#######| selection defined by <Uint-var> rather than the first        |#######
#######| @...PROMPT and specifies the MENU TO command to return on    |#######
#######| every keystroke that does NOT move the highlight bar to a    |#######
#######| new selection.                                               |#######
#######| ------------------------------------------------------------ |#######
#######| Only cursor movement in the orientatin of the menu moves the |#######
#######| menu bar.  For example, if the menu is oriented horizontally |#######
#######| the right and left cursor keys move the cursor bar, and up   |#######
#######| and down cursor keys exit the menu.                          |#######
#######| ------------------------------------------------------------ |#######
#######| Any key not related to cursor movement terminates the        |#######
#######| command with <Uint-var> containing the ID of the current     |#######
#######| selection.  Used with lastkey(), the MENU TO RETURN command  |#######
#######| can be used to create complex menuing systems with           |#######
#######| context-sensitive help.                                      |#######
#######| ------------------------------------------------------------ |#######
#######| When using RETURN, the <Uint-var> must contain the starting  |#######
#######| ID value for the menu selection.  If <Uint-var> is out of    |#######
#######| range, it is set to the first valid ID within the @...PROMPT |#######
#######| menu.                                                        |#######
#######| ------------------------------------------------------------ |#######
#######| The CLEAR MENU command must be called after MENU TO RETURN   |#######
#######| because the state of @...PROMPT is always saved.             |#######
#######| ------------------------------------------------------------ |#######
#######| SAVE                                                         |#######
#######|                                                              |#######
#######| 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.                                                     |#######
#######| ------------------------------------------------------------ |#######
#######| SAVE is not necessary if RETURN has been specified.  RETURN  |#######
#######| implies a SAVE of the menu.                                  |#######
#######+--------------------------------------------------------------+#######
##############################################################################
##############################################################################
#########+--| Example 1 |-------------------------------------------+#########
#########| *    Implement a simple menu.                            |#########
#########|                                                          |#########
#########| PROCEDURE force_main                                     |#########
#########|     VARDEF                                               |#########
#########|         UINT    sel_id                                   |#########
#########|     ENDDEF                                               |#########
#########|                                                          |#########
#########|     @ 1, 0 PROMPT "Add"                                  |#########
#########|     @ 1,10 PROMPT "Edit"                                 |#########
#########|     @ 1,20 PROMPT "Quit"                                 |#########
#########|                                                          |#########
#########|     MENU TO sel_id                                       |#########
#########|     IF lastkey() <> &K_ESC                               |#########
#########|         DO menu_case WITH sel_id                         |#########
#########|     ENDIF                                                |#########
#########| ENDPRO                                                   |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 2 |-------------------------------------------+#########
#########| *    Use the RETURN keyword do you can process up        |#########
#########| *    and down cursor keys while MENU TO processes        |#########
#########| *    left and right cursor keys.                         |#########
#########|                                                          |#########
#########| SET MESSAGE TO 1                                         |#########
#########| @ 0, 0  PROMPT "Edit"   MESSAGE "Edit a record."         |#########
#########| @ 0, 7  PROMPT "GOTO"   MESSAGE "GOTO a record."         |#########
#########| @ 0,14  PROMPT "Delete" MESSAGE "Delete a record."       |#########
#########| @ 0,19  PROMPT "Quit"   MESSAGE "Return to DOS."         |#########
#########| @ 2,0 TO 24,79 DOUBLE                                    |#########
#########|                                                          |#########
#########| MENU TO id_value RETURN                                  |#########
#########| IF lastkey() = &K_RETURN                                 |#########
#########|     DO CASE                                              |#########
#########|         CASE id_value = 1                                |#########
#########|             ?? "Planes was selected."                    |#########
#########|         CASE id_value = 2                                |#########
#########|             ?? "Trains was selected."                    |#########
#########|         CASE id_value = 3                                |#########
#########|             ?? "Cars was selected.  "                    |#########
#########|         CASE id_value = 4                                |#########
#########|             ?? "Boats was selected. "                    |#########
#########|     ENDCASE                                              |#########
#########| ELSE                                                     |#########
#########|      IF lastkey() = &K_UP                                |#########
#########|          DO scroll_up                                    |#########
#########|      ENDIF                                               |#########
#########|      IF lastkey() = &K_DOWN                              |#########
#########|          DO scroll_down                                  |#########
#########|      ENDIF                                               |#########
#########| ENDIF                                                    |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 3 |-------------------------------------------+#########
#########| *    When RETURN is used you can program your            |#########
#########| *    own "accelerator" keys.  Assume the menu is:        |#########
#########| *    Edit   Delete   Goto    Print   Quit                |#########
#########|                                                          |#########
#########| MENU TO zmenu RETURN                                     |#########
#########| t = (at( chr(k), "EeDdGgPpQq" )+1)/2                     |#########
#########| IF t <> 0 .AND. k < 256                                  |#########
#########|     zmenu = &ID_FILE + t                                 |#########
#########|     k = 13                                               |#########
#########|     select_prompt( zmenu, lastkey())                     |#########
#########| ENDIF                                                    |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 4 |-------------------------------------------+#########
#########| *    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.              |#########
#########|                                                          |#########
#########| PROCEDURE help_box                                       |#########
#########|  PARAMETERS VALUE UINT selection_pad                     |#########
#########|     GOTO selection_pad                                   |#########
#########|     m_edit( h->m, 18,50,24,77,.T.)                       |#########
#########| ENDPRO                                                   |#########
#########|                                                          |#########
#########|     {...}                                                |#########
#########|     MENU TO q ON SELECT DO help_box                      |#########
#########+----------------------------------------------------------+#########
##############################################################################