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

Function:    BOXMENU()

Purpose:     Create boxed framed highlight bar (pop up) menus.

Syntax:      BOXMENU( row, column, options [, choice [, altkeys;
                      [, exitkeys [, messages [, msg_row [, colors;
                      [, header [, restore ]]]]]]]]] )

Arguments:   row         - Numeric value indicating the row for the top
                           left corner of the menu box.  Value must be
                           between 0 and 24, or MAXROW() in the Clipper
                           5.0 version.

             column      - Numeric value indicating the column for the top
                           left corner of the menu box.  The value must be
                           between 0 and 79, or MAXCOL() in Clipper 5.0.

             options     - Array of character strings to use as menu
                           options.  Each element of the array is
                           displayed as a menu option filling the box.

             choice      - Optional numeric value indicating the starting
                           menu option number.  Value checked to be
                           between 1 and the number of elements in the
                           option array.  If an out of range value is
                           given, the starting number will be 1.

             altkeys     - Optional character string indicating what keys
                           may be pressed to select the corresponding menu
                           option.  The default is the first letter of
                           each of the menu options but, if this string is
                           provided, it is added to that list.  The
                           requirement is that the AT() position of the
                           character in the alternate key list is the
                           numeric equivalent of the corresponding menu
                           choice.

             exitkeys    - Optional character string indicating which keys
                           if pressed will cause an exit and return zero.
                           If omitted or an empty (or null) string is
                           specified, the Escape Key will default to being
                           the only key to cause a return zero exit.  If
                           this parameter is specified as a logical .F.,
                           no keys will cause a return 0 exit (it will be
                           disabled), and only the Enter Key will cause an
                           exit condition.

             messages    - Optional array of character strings to display
                           as messages corresponding to each of the menu
                           options.

             msg_row     - Optional numeric value indicating the row for
                           the optional prompt messages to appear.  This
                           value must be between 0 and 24, or MAXROW() in
                           the Clipper 5.0 version.  The default is row
                           24.  In the 5.0 version the default row is
                           MAXROW(), the bottom screen row.

             colors      - Optional array of character strings specifying
                           the color settings to use.  The colors used for
                           the different parts of the menu are specified
                           as follows:

                              color[1] -  Menu choices (item options)
                              color[2] -  Menu selection bar
                              color[3] -  Active menu box (on entry)
                              color[4] -  Inactive menu box (on exit)
                              color[5] -  Menu choice upon selection
                              color[6] -  Messages displayed on promptrow

             header      - Optional character string which, if supplied
                           will force BOXMENU() to extend the box around
                           the menu to include a header area.  The string
                           supplied will be centered in this area as a
                           menu title.  See BORDERBOX() for additional
                           details.

             restore     - Optional logical value indicating whether or
                           not to save and restore the screen region
                           underneath the menu on exit.  The default is
                           false.

Returns:     The number of the array element option picked, or 0 if escape
             was pressed.

Description: BOXMENU() follows a popular and logical sequence for
             producing box style menus.  The active menu is surrounded by
             a double line box.  When it becomes inactive after a choice
             is made, the box border changes to a single line to indicate
             the menu is no longer active.  If the row and/or column
             positions supplied are out of bounds (not between 0 and 24
             (MAXROW() in 5.0 version), and 0 and 79) a default row or
             column of 1 will be used.  Also, since this is mainly a menu
             building tool, no provision has been made to scroll menu
             items below the bottom of the menu box.  Consequently, you
             should consider how many options will be in the menu when
             determining the top row, as the bottom of the box is
             calculated by adding the number of options in the array.  If
             more elements exist in the array than will fit in the box,
             unpredictable screen displays will occur.  This exclusion was
             made for the benefit of speed and compactness of code.  If a
             scrollable menu is needed, use ACHOICE().

Notes:       If an optional parameter is skipped, you must pass a dummy in
             its place.

             If you use the color feature, DECLARE your colors array to
             have at least 6 elements.  If the colors option is not
             specified or there are less than 5 elements, then the default
             colors are used.  These defaults are: the current Standard
             color is used for the box and item displays, and the Enhanced
             color is used for the menu bar.  The sixth element is new to
             version 3.0 (See below)

             The colors array may now contain six elements.  The sixth
             element is used as the color for displaying the optional
             messages on <promptrow>.  In RLIB version 2.0, these messages
             used to be displayed in the same color as the menu options
             which was not always (and rarely) desirable.  To maintain
             upward compatibility, the color array table may remain at 5
             elements.  The 6th element is optional.  If the 6th element
             for the optional messages color is not given, then the Option
             color (element #1) is used.


Example:     *-- declare arrays for menu and message options
             DECLARE option[5], message[5]

             *-- menu choices
             option[1] = " 1.  Add new records (Append) "
             option[2] = " 2.  Edit records    (Change) "
             option[3] = " 3.  Delete records  (Remove) "
             option[4] = " 4.  Update records  (Modify) "
             option[5] = " 5.  Quit and return (eXit)   "

             *-- corresponding messages
             message[1] = "Add new records to the database"
             message[2] = "Edit records already in the database"
             message[3] = "Delete selected records"
             message[4] = "Update dates of last appointments"
             message[5] = "Leave this menu and return to previous"

             *-- in addition to 1,2,3,4, or 5, (default select keys)
             *-- let the following keys also select the choices
             alt_keys = 'AEDUQ' + 'ACRMX'

             DECLARE colors[6]
             colors[1] = 'N/BG'      && options are Black on Cyan
             colors[2] = 'W+/GR'     && menu bar is Bright White on Brown
             colors[3] = 'R+/BG'     && active menu is Bright Red on Cyan
             colors[4] = 'R/BG'      && in-active is Red on Cyan
             colors[5] = 'R/BG'      && selected choice is Red on Cyan
             colors[6] = 'BG/N'      && messages are Cyan on Black

             *-- allow Escape and Left and Right arrow keys to exit
             exit_keys = CHR(27) + CHR(19) + CHR(4)

             *-- start with first choice
             choice = 1

             *-- header message
             header = "AVAILABLE OPTIONS"

             *-- put up menu on row 2, column 10, with messages on row 24
             choice = BOXMENU( 2,10, option, choice, alt_keys, exit_keys,;
                               message, 24, colors, header )

Source:      RL_BOXME.PRG

See also:    BARMENU(), MULTIMENU(), PDOWNMENU()