<<About Text Mode Colors>>
<Text Mode Colors>
Text Mode Colors

In text mode, every character position on the display has a video
attribute byte that designates a foreground and background color.  The
pixels that form the character use the foreground color and the
remaining pixels use the background color.  In other words, the
background is the paper color and the foreground is the ink color.

<Standard Color Codes>
Standard Color Codes

Color video adapters (CGA, EGA, VGA and SVGA) support 16 different
colors designated by color codes 0 through 15.  Colors 8 through 15
are normally bright (enhanced) versions of colors 0 through 7,
respectively:

         0 Black        8 Gray
         1 Blue         9 Bright Blue
         2 Green       10 Bright Green
         3 Cyan        11 Bright Cyan
         4 Red         12 Bright Red
         5 Magenta     13 Bright Magenta
         6 Brown       14 Yellow
         7 White       15 Bright White

16 foreground and 16 background colors produce 256 different color
combinations--exactly the capacity of the video attribute byte.  In
the normal state of a video adapter, however, one bit is used to
designate blinking.  In this state, only color codes 0 through 7 can
be used as background colors.

The normal state of a video adapter is set by the boot process.  This
state can be altered to disable blinking.  With blinking disabled, all
sixteen color codes can be used as both foreground and background.
The Clarion statements SETNOBLINK and SETBLINK disable and enable
blinking.

<Standard RGB Values>
Standard RGB Values

On VGA and SVGA video adapters colors are produced by varying the
intensity of red, green, and blue light on a scale of 0 to 63.  RGB
values or 0,0,0 produce black (no light).  An RGB value of 63,63,63
produces bright white.  The following standard RGB values are used to
produce the normal 16 text colors:

         0,0,0    Black      21,21,21    Gray
        0,0,42    Blue       21,21,63    Bright Blue
        0,42,0    Green      21,63,21    Bright Green
       0,42,42    Cyan       21,63,63    Bright Cyan
        42,0,0    Red        63,21,21    Bright Red
       42,0,42    Magenta    63,21,63    Bright Magenta
       42,21,0    Brown      63,63,21    Yellow
      42,42,42    White      63,63,63    Bright White

VGA and SVGA video adapters permit these 16 text colors to be reset to
any RGB value.  That provides 16 out of 262,144 (64x64x64) colors for
new color schemes.  The function RGB and the procedure SETRGB are
provided in this package to read and write RGB values from a Clarion
program.


<<Using Spectrum>>
<Introduction>
Spectrum mixes red, green, and blue values to produce new color
schemes for VGA and Super VGA monitors.  A color scheme consists of
the color names and RGB values for the 16 text mode colors.  Color
schemes are stored in ASCII color text files that contain 16 records
with the color name, red value, green value, and blue value separated
by commas.  Color names must be less than 15 characters long.  RGB
values range from 0 to 63.  Color text files are used by the Clarion
environment, by the SETRGB program, and by any other "RGB aware"
Clarion program.

<Selecting a Color>
Selecting a Color

The color chart at the top of the screen shows the current color
names and RGB values of the 16 text mode colors.  One color is
enclosed by a frame.  This is the selected color.

To change the selected color, click on any other color with the left
mouse button.  Or press the cursor or tab keys to move the color
frame.  Then press enter.

<The Color Name Field>
The Color Name Field

Click on the Color Name field or press the cursor or tab keys to
select the Color Name field.  Then enter a new color name and press
the tab or Enter key.  The color name is then placed in the color
chart and will be written to the color text file when it is saved.

<The Sample Foreground Field>
The Sample Foreground Field

Click on the Sample Foreground field or press the cursor or tab keys
to select the Sample Foreground field.  Then enter 0 to 15 to change
the foreground color used to display the RGB values immediately below.
The selected color is displayed as the background.  This field is not
saved in the color ext file.  It is only used to ensure that the RGB
display can be made visible against any background.

<Mixing Colors>
Mixing Colors

The red, green, and blue intensity values range from 0 to 63.
Pressing a More button increases the intensity of the color listed
below.  If that intensity is already at its maximum value of 63, the
More button decreases the intensity of the other two colors.

Similarly, pressing a Less button decreases the intensity of the color
listed above.  If that intensity is already 0, the Less button does
nothing.

The Darker button decreases the intensity of any color with an
intensity greater than 0.  Similarly, the Lighter button increases the
intensity of any color with an intensity less than 63.

<The File Menu>
The File Menu

File/Open...     Displays the "Open File" dialog box to select a
                 drive, path, and filename.  If a valid color text
                 file is selected, its contents are loaded and
                 displayed in the color chart.  The file specification
                 is displayed on the Spectrum title bar and the
                 File/Close and File/Save menu items are enabled.

File/Close...    Writes the current color names and RGB values from
                 the color chart to the active file and deactivates
                 the file, removing the file specification for the
                 Spectrum title bar and disabling the File/Close and
                 File/Save menu items.  If no file is active, this
                 menu item is disabled.

File/Save...     Writes the current color names and RGB values from
                 the color chart to the active file.  If no file is
                 active, this menu item is disabled.

File/Save As...  Displays a "Save File As" dialog box to name a new
                 active file.  If a valid filename is entered, it is
                 updated with the current color names and RGB values.
                 This file then becomes the active file.

File/Exit        Restore the RGB values to their initial value and
                 exits the program.

<The Edit Menu>
The Edit Menu

Edit/Restore Standard RGB        Restores the standard RGB settings to
                                 the selected color.

Edit/Restore Initial RGB         Restores the RGB settings at the time
                                 the program started to the selected
                                 color.

Edit/Restore File RGB            Restores the RGB settings at the time
                                 the active file was opened to the
                                 selected color.

Edit/Restore All Standard RGBs   Restores the standard RGB settings to
                                 all colors.

Edit/Restore All Initial RGBs    Restores the RGB settings at the time
                                 the program started to all colors.

Edit/Restore File RGB            Restores the RGB settings at the time
                                 the active file was opened to all
                                 colors.


<<Designing Color Schemes>>

If you are designing a color scheme for multiple programs or for a
program that can launch other programs, there are certain conventions
to keep in mind.  Very few text mode programs modify or check RGB
values.  If you change the color scheme, most programs will simply use
the new colors.

Therefore any new color scheme should augment rather than completly
replace the normal scheme.  Some colors, such as bright magenta are
rarely used and can safely be set to any RGB value.  Black, Blue, Red,
Gray, White, Yellow, and Bright white are commonly used.  These colors
can be modified slightly in intensity and tone, but should retain
their general character.

The standard RGB values used for Green and Brown produce ugly colors
that aren't very popular.  The RGBs can be easily remixed to very
attractive and useable versions of these colors.  Cyan and Magenta are
somewhat unusual colors that are neither popular nor attractive.
These colors can usually be safely changed to other colors.

The bright colors, other than gray, yellow, and bright white are
rarely used and should be remixed to other more useable colors.  In
Clarion programs, window shadows subtract 8 from color codes 8 to 15
and change color codes 0 to 7 to gray on black.  If you are planning
to use shadows, you should pair up lighter with darker colors.

The color scheme shipped with this package (CUSTOM.CLR) was designed
to produce programs in positive video (dark ink on light paper).  The
paper colors are white, cream, beige, silver, pink, and sky blue.  The
ink colors are black, charcoal, blue, green, gray, and burgundy, and
brown.  Yellow and Bright White can be used for accents.

    To produce two more shades of gray, Cyan becames gray, Bright Cyan
    becomes Silver (a lighter gray).  Then the original Gray was
    darkened to Charcoal and the original White was lightened.  This
    produced six "shades of gray" equally spaced from Black (0,0,0) to
    Bright White (63,63,63).

    Blue was darkened slightly and Bright blue was substantially
    lightened to sky blue.

    Green was darkened to a forest green shade that would be an
    attractive foreground for White, Silver, Beige, or Cream
    backgrounds.  Bright Green was changed to Cream.

    Red was not changed and Bright Red was changed to Pink.

    Magenta was changed to Burgundy, another color attractive
    foreground for White, Silver, Beige, and Cream.  Bright Magenta
    was changed to Beige.

    Brown was remixed to a more attractive shade and Yellow was
    unchanged.

The Clarion styles file (CUSTOM.STY) can be used to adapt this color
scheme to the Clarion Environment.


<<Displaying Color Schemes>>

SETRGB.EXE displays and restores color schemes.  If the SETGRGB
command names a color text file (e.g.  SETRGB NEWCOLOR.CLR), the
RGB values are set to the contents of the file.  If the SETRGB
command contains a /R parameter, the RGB values are restored to their
standard settings.

<<Coloring Clarion Programs>>

The RGB oject library can be included into your Clarion program by
adding the object module "%clapfx%RGB.LIB" to your project file.  This
object library contains the following functions and procedures:

    SaveRGB saves the current RGB values (to be restored later).

    RestoreRGB restores the RGB values that were saved.  If none were
               saved, RestoreRGB restores the standard RGB values.

    LoadRGB(file) loads the RGB values it finds in the color text file
                  given as a parameter.  If the file cannot be found,
                  or is not a color text file, no action is taken.

    RGB(color) is a function that returns the current red, blue, and
               green intensity values for the given color in the low
               order three bytes of a long integer.

    SetRGB(color,red,green,blue) sets the given color to the given
                                 red, green, and blue intesity values.

To hard code custom colors into your Clarion program, place the
desired RGB values into a structure such as this:

    I              BYTE
    RGBValues      GROUP
                     STRING('<0,0,0><0,0,37><0,24,0><31,31,31>')
                     STRING('<42,0,0><36,1,21><32,21,3><51,51,51>')
                     STRING('<22,22,22><50,50,63><61,55,40><45,45,45>')
                     STRING('<63,48,48><62,59,48><63,63,21><63,63,63>')
                   END
                   GROUP,DIM(16),OVER(RGBValues)
     Red             BYTE
     Green           BYTE
     Blue            BYTE
                   END

Then to activate this color scheme:

     LOOP I = 1 to 16
       SetRGB(I-1,Red[I],Green[I],Blue[I])
     END

<<Coloring the Clarion Environment>>

The example custom color scheme (CUSTOM.CLR) is very attractive when
used with the Clarion Evnironment.  While Clarion is not running:

    1.  Copy SETRGB.EXE, CUSTOM.STY, and CUSTOM.CLR to the \CLARION3
        directory.

    2.  In CLARION3.INI, Add CLA_COLORS_TXT=CUSTOM.CLR.  This provides
        new color names for the screen color selection guide.

    3.  In CLARION3.INI, change STYLE_FILE=CLARION.STY to
        STYLE_FILE=CUSTOM.STY.  This tells the environment where the
        the new colors should be used.

    4.  In CDD3.BAT, set the new RGB values before and reset the
        standard RGB values after running CLARION3:

                SETRGB CUSTOM.CLR
                CLARION3
                SETRGB /R

If the RGB values are reset to their standard values while CUSTOM.STY
is in use, the color scheme becomes garish and unreadable.  To correct
this situation, run SETRGB CUSTOM.CLR from the DOS Shell or from the
DOS prompt.

<<Contents of the Spectrum Package>>

SPECTRUM.EXE   SPECTRUM is the color scheme design program.  Color
               schemes are saved in ASCII color text files.  Color
               text files contain exactly 16 records that contain the
               color name and RGB values for the 16 color codes used
               in text mode.

SPECTRUM.CLA
SPECTRU1.CLA  Source modules for SPECTRUM.EXE
SPECTRU2.CLA

SPECTRUM.PR    Project file to build SPECTRUM.EXE
SPECTRUM.HLP   Help file for SPECTRUM.EXE
SPECTRUM.TXT   Help text for SPECTRUM.EXE

SETRGB.EXE     "SETRGB file" sets the current colors to the RGB values
               listed in the file parameter.  "SETRGB /R" resets the
               current colors to their standard RGB values.  SETRGB
               with no parameters displays the parameter useage on the
               console.

SETRGB.CLA     Source module for SETRGB.EXE
SETRGB.PR      Project file to build SETRGB.EXE

DDVRGB.LIB    Object library modules for the SaveRGB,
DOVRGB.LIB    RestoreRGB, and LoadRGB procedures
DXVRGB.LIB
DEVRGB.LIB
DESRGB.LIB
DDVRGB.DLL    DLL for DDVRGB.LIB
DESRGB.DLL    DLL for DESRGB.LIB

RGB.CLA        Source module for RGB.EXE
RGB.PR         Project file to build RGB.EXE
RGB.INC        Include file for other program's MAPs

DDVLLRGB.LIB  Low level object modules for the RGB function and
DOVLLRGB.LIB  SetRGB procedure (written in C).
DXVLLRGB.LIB
DEVLLRGB.LIB
DESLLRGB.LIB
DDVLLRGB.DLL  DLL for DDVLLRGB.LIB
DESLLRGB.DLL  DLL for DESLLRGB.LIB

LLRGB.INC      Include file for other program's MAPs

CUSTOM.CLR     Color text file for the example custom color scheme
CUSTOM.STY     Styles file for the Clarion environment to use the
               custom color scheme.

<<Open File>>

Select an existing file to open from the Files Listbox by highlighting
the desired file and pressing Enter.

By default, the files initially displayed have an extension of CLR.
The default may be changed to a different mask by typing a new mask
in the File Mask field and pressing Enter or Tab.

Use the Directories list box to access files in other directories on
the disk.

<<Save File As>>

Enter a filename to save the color set and customized RGB settings.
Press Enter to accept the file, or Esc to cancel.

<<Warn File Exists>>

The filename entered is an existing file.  Select Yes to save
color changes and overwrite the file, or select No to cancel
this file name.

<<Warn Color Changes>>

A request to Open a file has occurred after making changes to the
color scheme without saving.  Continuing will result in the loss
of the current changes.

To open a new file and lose current changes, select Yes.

To preserve the current changes and return to SPECTRUM, select No.

<<Warn Save Changes>>

Exit has been selected after making changes that have not been saved.
You may save changes and exit, not save changes and exit, or cancel
the exit request.

To save changes, select Yes.  Changes will be written to the currently
open file.  If a file has not been opened, the Save As window will
prompt for a file name.

To exit without saving, select No.

To remain in SPECTRUM, select Cancel.

<<Warn Bad File>>

The file requested is not a valid colors file, and cannot be
loaded.  Press Enter to return to SPECTRUM.

<<Check Video Type>>

SPECTRUM has determined that the video hardware available is not VGA
or SVGA.  The SPECTRUM color handling abilities are only suited to
VGA and SVGA hardware.

You may still run SPECTRUM and modify color values.  However, the
colors will not visually change on this hardware.

Press Enter to complete the warning screen and continue with SPECTRUM.
