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

Function:    MULTIMENU()

Purpose:     Create multi-column menus with four way cursor movement.

Syntax:      MULTIMENU( t, l, b, r, options [, columns [, messages ;
                         [, msg_row [, colors ] ] ] ] )

Arguments:   t,l,b,r     - Numeric values specifying the Top, Left, Bottom
                           and Right screen coordinates of the display
                           box.  The top and bottom row values must be
                           between 0 and 24 (MAXROW() in 5.0), and the
                           left and right column values must be between 0
                           and 79.

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

             columns     - Optional numeric value indicating the number of
                           columns to use for displaying the options.  If
                           omitted or a non numeric parameter is passed,
                           or if it is zero, the columns will be
                           calculated to fit the most options across the
                           left and right window boundaries.

             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 messages to appear.  This value
                           must be between 0 and 24 (MAXROW() in 5.0).
                           The default is row 24, or MAXROW() in the
                           Clipper 5.0 version.

             colors      - Optional array of character strings specifying
                           the color settings to use.  See the color table
                           below for the colors used for the different
                           components of the menu.

Returns:     The number of the array element chosen, or zero if the escape
             key was pressed.

Description: MULTIMENU is a multi-column menu selection function.  Many
             programs offer a list of options to choose from displayed
             across the screen allowing you to cursor up, down, left and
             right to navigate around the options.  This function takes an
             array of character strings and displays them in this format.

Notes:       If any of the first four parameters specifying the window
             coordinates are out of bounds, or the <right> is less than or
             equal to <left>, or <bottom> is less than or equal to <top>,
             MULTIMENU() will fail and return zero.  Also, if the options
             array is empty, a zero will be returned.  If the number of
             columns option is omitted (or zero to make the number of
             columns automatic), MULTIMENU() will position columns so that
             columns are separated by at least one space.  If more
             elements exist in the array than will fit in the display
             window given the number of columns being used, the PgDn and
             PgUp keys will skip forward and back between windows.

             The following color table shows which features of the menu
             each element of the color array controls:

                         colors[1] = Menu choices.
                         colors[2] = Menu selection bar.
                         colors[3] = <not used>
                         colors[4] = <not used>
                         colors[5] = Selected choice on exit.

             If you use this color feature, DECLARE your colors array to
             have at least 5 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 item displays, and the Enhanced color
             is used for the menu selection bar.


Example:     *-- display fields in box with structure for each shown below
             USE manyflds.dbf

             *-- declare arrays for field names
             num = FCOUNT()
             DECLARE fields[num], types[num], widths[num], dec[num]
             DECLARE struct[num]
             AFIELDS( fields, types, widths, dec )  && fill with .DBF info

             FOR x = 1 TO num
                *-- now make each field name 12 spaces wide
                fields[x] = STRETCH(fields[x],12)
                *-- and build field description message for each
                struct[x] = IF( types[x] = "C", "Character",;
                            IF( types[x] = "N", "Numeric",;
                            IF( types[x] = "L", "Logical",;
                            IF( types[x] = "D", "Date", "Memo")))) +;
                            "  Length: "   + STR(widths[x],3,0) +;
                            "  Decimals: " + STR(dec[x],3,0)
             NEXT x
             *-- now present these fields in a single line box
             @ 1,0,10,79 BOX "+-+|+-+|"

             *-- present fields with structure for each on line 11
             *-- the zero makes UDF calc column number dynamically
             fieldnum = MULTIMENU( 2,1,9,78, fields, 0, struct, 11 )

Source:      RL_MULTI.PRG

See also:    BARMENU(), BOXMENU()