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

Function:    BARMENU()

Purpose:     Create horizontal light bar menus.

Syntax:      BARMENU( row, options [, columns [, start [, altkeys [,;
                      exitkeys [, messages [, msg_row [, colors ]]]]]]])

Arguments:   row         - Numeric value which indicates the row on which
                           the bar menu is to appear.  Value must be
                           between 0 and 24, or MAXROW() in the Clipper
                           5.0 version.

             options     - Array of character strings to display as bar
                           menu option choices.

             columns     - Optional array of numeric values used as column
                           numbers on which to display each option.

             start       - Optional starting array element number for the
                           menu option to highlight upon start-up.

             altkeys     - Optional list of alternate selection keys which
                           when pressed, cause an option to be selected.

             exitkeys    - Optional list of keys to cause a zero return
                           value exit.  Pass a null string to skip.  The
                           default key is Escape.  Pass a value of False
                           (.F.) to disable the zero return value exit
                           capability altogether.

             messages    - Optional array of menu option messages which
                           are displayed as each menu option is
                           highlighted.

             msg_row     - Optional row number on which these messages
                           appear.  The default row for these messages in
                           row 24.  In the Clipper 5.0 version the default
                           message row in 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:

                              colors[1] = Menu options
                              colors[2] = Menu highlight bar
                              colors[3] = <not used>
                              colors[4] = Menu messages
                              colors[5] = Selected option on exit

Returns:     A numeric value indicating the number of the array element
             option selected or zero if the escape key was pressed (or one
             of the <exitkeys>).

Description: BARMENU() makes creating horizontal light bar menus a snap.
             Although creating this type of menu has been simplified with
             Clipper's PROMPT and MENU TO commands, this function offers
             additional flexibility while keeping your code to a minimum.

Notes:       In the Clipper 5.0 version of BARMENU(), the <row> parameter
             may be any row value between 0 and MAXROW().

             Optional parameters are not required, but if you wish to skip
             an optional parameter, you must pass a dummy value.  The best
             dummy value to use is a null string "" (set up a memvar named
             dummy where dummy = "").

             In addition to the right and left arrow keys, the space bar
             and back space keys move the menu bar to the right and left.
             The menu bar line background (color[4]) is used to clear the
             menu line and place it in that color.

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

             *-- menu choices
             option[1] = 'File'
             option[2] = 'Edit'
             option[3] = 'Next'
             option[4] = 'Previous'
             option[5] = 'Quit'

             *-- corresponding message prompts
             prompt[1] = 'Load, Save, Transfer, Erase, Quit'
             prompt[2] = 'New orders, Repairs, Exchanges, Quit'
             prompt[3] = 'Skip to the next entry'
             prompt[4] = 'Skip to the previous entry'
             prompt[5] = 'Quit and return to DOS'

             *-- set up column position numbers so options fill screen
             *-- File        Edit        Next        Previous       Quit

             *-- if omitted options will look like this:
             *-- File  Edit  Next  Previous  Quit
             column[1] =  0
             column[2] = 18
             column[3] = 36
             column[4] = 54
             column[5] = 76

             *-- let the down and up arrows also select Next and Previous
             *-- the AT() position of altkeys in the string must match the
             *-- corresponding array element number.
             altkeys = 'FE' + CHR(24) + CHR(5) + 'Q'

             *-- set up colors to be used
             DECLARE colors[5]
             colors[1] = 'B/BG'            && options are Blue on Cyan
             colors[2] = 'B/W'             && menu bar is Blue on White
             colors[3] = ''                && not used
             colors[4] = 'B/BG'            && menu line also Blue on Cyan
             colors[5] = 'W+/BG'           && selected option Bright White

             *-- keep Escape from causing exit, force them to press Q
             xitkeys = .F.

             *-- initial choice = 'File' = 1
             choice = 1        && initial menu choice is #1, File
             toprow = 1        && put menu on top row, row #1
             msgrow = 2        && show menu messages on row #2

             *-- display menu on row 1 with messages on row 2
             choice = BARMENU( toprow, column, option, choice, altkeys,;
                               xitkeys, prompts, msgrow, colors )

Source:      RL_BARME.PRG

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