SETCOLOR()
 Return the current colors and optionally set new colors
------------------------------------------------------------------------------
 Syntax

     SETCOLOR([<cColorString>]) --> cColorString

 Arguments

     <cColorString> is a character string containing a list of color
     attribute settings for subsequent screen painting.  The following is a
     list of settings and related scopes:

     Color Settings
     ------------------------------------------------------------------------
     Setting        Scope
     ------------------------------------------------------------------------
     Standard       All screen output commands and functions
     Enhanced       GETs and selection highlights
     Border         Border around screen, not supported on EGA and VGA
     Background     Not supported
     Unselected     Unselected GETs
     ------------------------------------------------------------------------

     Each setting is a foreground and background color pair separated by the
     slash (/) character and followed by a comma.  All settings are optional.
     If a setting is skipped, its previous value is retained with only new
     values set.  Settings may be skipped within the list or left off the end
     as illustrated in the examples below.

 Returns

     SETCOLOR() returns the current color settings as a character string.

 Description

     SETCOLOR() is a screen function that saves the current color setting or
     sets new colors for subsequent screen painting.  A color string is made
     from several color settings, each color corresponding to different
     regions of the screen.  As stated above, each setting is made up of a
     foreground and background color.  Foreground defines the color of
     characters displayed on the screen.  Background defines the color
     displayed behind the character.  Spaces and nondisplay characters
     display as background.

     In CA-Clipper, the settings that define color behavior are:

     Standard: The standard setting governs all console, full-screen, and
     interface commands and functions when displaying to the screen.  This
     includes commands such as @...PROMPT, @...SAY, and ?, as well as
     functions such as ACHOICE(), DBEDIT(), and MEMOEDIT().

     Enhanced: The enhanced setting governs highlighted displays.  This
     includes GETs with INTENSITY ON, and the MENU TO, DBEDIT(), and
     ACHOICE() selection highlight.

     Border: The border is an area around the screen that cannot be
     written to.

     Background: The background is not supported.

     Unselected: The unselected setting indicates input focus by
     displaying the current GET in the enhanced color while other GETs are
     displayed in the unselected color.

     In addition to colors, foreground settings can have high intensity
     and/or blinking attributes.  With a monochrome display, high intensity
     enhances brightness of painted text.  With a color display, high
     intensity changes the hue of the specified color.  For example, "N"
     displays foreground text as black where "N+" displays the same text as
     gray.  High intensity is denoted by "+".  The blinking attribute causes
     the foreground text to flash on and off at rapid intervals.  Blinking is
     denoted with "*".  The attribute character can occur anywhere in the
     setting string, but is always applied to the foreground color regardless
     where it occurs.  See SETBLINK() for additional information.

     The following colors are supported:

     List of Colors
     ------------------------------------------------------------------------
     Color          Letter    Monochrome
     ------------------------------------------------------------------------
     Black          N, Space  Black
     Blue           B         Underline
     Green          G         White
     Cyan           BG        White
     Red            R         White
     Magenta        RB        White
     Brown          GR        White
     White          W         White
     Gray           N+        Black
     Bright Blue    B+        Bright Underline
     Bright Green   G+        Bright White
     Bright Cyan    BG+       Bright White
     Bright Red     R+        Bright White
     Bright Magenta RB+       Bright White
     Yellow         GR+       Bright White
     Bright White   W+        Bright White
     Black          U         Underline
     Inverse Video  I         Inverse Video
     Blank          X         Blank
     ------------------------------------------------------------------------

 Notes

     .  Arguments are not specified: Unlike SET COLOR TO, SETCOLOR()
        with no argument does not restore colors to their default values.

     .  Color numbers: SETCOLOR() supports color letter combinations,
        but not color number combinations.

 Examples

     .  This example assigns the current color setting to the
        variable, cColor:

        cColor:= SETCOLOR()

     .  This example uses SETCOLOR() to save the current color setting
        and set a new one.

        cNewColor:= "BR+/N, R+/N"
        cOldColor:= SETCOLOR(cNewColor)

     .  This example uses SET COLOR TO to reset the default colors:

        SET COLOR TO
        ? SETCOLOR()            // Result: W/N, N/W, N, N, N/W

     .  These two examples specify SETCOLOR() with missing settings:

        // Settings left off the end
        SETCOLOR("W/N, BG+/B")
        //
        // Settings skipped within the list
        SETCOLOR("W/N, BG+/B,,,W/N")

     .  This example uses SETCOLOR() with ISCOLOR() to set the colors,
        depending on the screen type:

        FUNCTION DefaultColors
           IF ISCOLOR()
              cForm := "W+/N, BG+/B,,,W/N"
              cDialog := "N/N+, BG+/B,,,N/N+"
              cAlert := "W+/R, BG+/B,,,W+/R"
           ELSE
              cForm := "W+/N, N/W,,,W/N"
              cDialog := "W+/N, N/W,,,W/N"
              cAlert := "W+/N, N/W,,,W/N"
           ENDIF
           RETURN NIL

 Files   Library is CLIPPER.LIB.