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

Function:    PICKCOLOR()

Purpose:     Pick a color setting from a boxed display.

Syntax:      PICKCOLOR( [ pick_color [, box_color [, x_string [, toprow;
                        [, leftcolumn [, show_names ] ] ] ] ] ] )

Arguments:   pick_color  - Character string indicating the initial color
                           to position the highlight bar on as the
                           selected color.  The default is the current
                           color setting.

             box_color   - Character string indicating the color to use
                           for the display box border and color names
                           text.  The default is the current color
                           setting.

             x_string    - String to use instead of the X's as the fill
                           characters in the color boxes.  The default
                           string is a five character string " XXX ".

             toprow      - Numeric value indicating the top row on which
                           to position the color grid box.  Valid range is
                           from 0 to 5.  If omitted or an invalid number
                           is given, the default row of 4 will be used.

             leftcolumn  - Numeric value indicating the left column of the
                           box display.  The default is calculated so as
                           to center the box on the screen.

             show_names  - Logical true or false indicating whether or not
                           to display the color names along the right side
                           of the selection box.  The default is True
                           (.T.)

Returns:     The selected color as a Clipper character color string, or a
             null string ("") if terminated by pressing the Escape key.

Description: PICKCOLOR() is very useful as a function to allow the user to
             interactively select a color setting from within an
             application.  PICKCOLOR() draws a box on the screen either
             centered or at the column you specify, and fills it with a
             grid of 16 rows by 8 columns of " XXX ", or the string you
             specify, displaying each of the 128 possible color
             combinations.  Optionally, the descriptive names of each of
             these colors is displayed to the right of the display box.
             At the bottom of the screen two sample lines are shown in the
             highlighted color setting.

Notes:       PICKCOLOR() occupies most of the screen area when displaying
             the color grid.  Initially PICKCOLOR() was designed to clear
             the screen.  This was later removed so that an application
             could leave instructions somewhere on the screen, perhaps the
             menu choice showing the user which color option they were
             selecting.

             PICKCOLOR() does save and restore the screen area underneath
             when it terminates.  The initial <pick_color> parameter
             determines where the highlight bar is initially positioned in
             the grid.

             The default x_string is " XXX " with automatic centering.  If
             you specify a longer (or shorter) string, and you also
             specify the left column, PICKCOLOR() will determine if the
             column you provided would cause the grid to fall off the
             screen.  If this happens, the grid will be shifted left the
             necessary number of columns.  All of these positioning
             considerations vary depending whether or not the color names
             are displayed, since they take up room on the right side of
             the grid.

Example:     *-- set up default screen color settings
             SETCOLOR("R/W,W/R,,,BG/R")

             *-- retrieve current Enhanced & Unselected color settings
             m_getcolor = GETPARM( 2, SETCOLOR() )
             m_unselect = GETPARM( 5, SETCOLOR() )

             *-- present routine to let user select GET color scheme
             @ 1,0 SAY "Select color for highlighted variables:"

             *-- pop up grid in White on Blue, showing blocks of " ## "
             *-- in the top right corner of the screen, no color names
             *-- Hint: the column of 79 forces right side alignment
             m_getcolor = PICKCOLOR(m_getcolor, "W/B", " ## ", 0, 79, .F.)

             @ 1,0 SAY "Select color for unselected variables:"
             m_unselect = PICKCOLOR(m_unselect, "W/B", " ## ", 0, 79, .F.)

Source:      RL_PICKC.PRG

See also:    BRIGHT(), GETPARM()