CLR_xx    ..
   Windows Color codes
------------------------------------------------------------------------------

  FiveWin has some predefined color codes that are similar to clippers
  string color representation. This means we can use colors in a 
  traditional way ( using clippers strings ) or use Windows RGB codes.

     CLR_BLACK              0          RGB(   0,   0,   0 )
     CLR_BLUE         8388608          RGB(   0,   0, 128 )
     CLR_GREEN          32768          RGB(   0, 128,   0 )
     CLR_CYAN         8421376          RGB(   0, 128, 128 )
     CLR_RED              128          RGB( 128,   0,   0 )
     CLR_MAGENTA      8388736          RGB( 128,   0, 128 )
     CLR_BROWN          32896          RGB( 128, 128,   0 )
     CLR_HGRAY       12632256          RGB( 192, 192, 192 )
     CLR_LIGHTGRAY   12632256          RGB( 192, 192, 192 )
     CLR_GRAY         8421504          RGB( 128, 128, 128 )
     CLR_HBLUE       16711680          RGB(   0,   0, 255 )
     CLR_HGREEN         65280          RGB(   0, 255,   0 )
     CLR_HCYAN       16776960          RGB(   0, 255, 255 )
     CLR_HRED             255          RGB( 255,   0,   0 )
     CLR_HMAGENTA    16711935          RGB( 255,   0, 255 )
     CLR_YELLOW         65535          RGB( 255, 255,   0 )
     CLR_WHITE       16777215          RGB( 255, 255, 255 )


  Graphical environments often use many more colors than we can represent 
  with clippers old color characters. Normally we will be using 256 up to
  16 millions of colors. The more colors you use, the more Windows will 
  slow down, as it has to manage more memory to perform the same processes.

  If you want to define a 'custom' color, use the RGB() pseudo function :

     +-------------------------------------------------------------+
     |  /* I like it orange */                                     |
     |  CLR_ORANGE := RGB( 255, 128, 0 )                           |
     +-------------------------------------------------------------+
     

 FiveWin Color management

  FiveWin extends the standard xBase DOS color management syntax to allow
  the use of the Windows and graphical environments enhanced capabilities
  RGB Colors and Brushes management.

  This means we can use colors in a traditional way (using xBase string
  color representation) or use Windows RGB and Brushes new capabilities.

  Let's review the DOS and Windows color structure and see how we can take
  advantage of all these features, from any level:

                    * xBase high-level commands
                    * Objects Data & Methods
                    * Clipper new functions
                    * C level new functions
                    * Windows API standard functions


 xBase DOS color management
 Standard DOS xBase color management is based on strings which are a
 combination of the following elements:

           Base colors

       Black ......... "N"                   Color structure
       Blue  ......... "B"
       Green ......... "G"         [ + ] [ * ] "<ForeColor> / <BackColor>"
       Cyan  ......... "BG"
       Red   ......... "R"
       Magenta ....... "RB"
       Brown ......... "GR"  (a/k/a yellow)
       White ......... "W"


  [ + ]             Intensity
  [ * ]             Blinking  or Back intensity
  <ForeColor>       One of the above base colors
  <BackColor>       One of the above base colors


  Example: If we want to use high intensity white letters on blue background,
           we have to use the following color string:

                  "W+/B"   -->    "W"  White ForeColor
                                  "+"  High intensity ForeColor
                                  "B"  Blue BackColor


 At the DOS hardware level, colors have the following structure:

                           Screen internal map

          <Char><Color><Char><Color><Char><Color><Char><Color>....

  Where <Char> is each of the characters we see on the screen and <Color>
  is the color of each character (attribute). Each <Color> is represented
  in only one byte.


      Binary representation
         of a byte color

    X  X  X  X  X  X  X  X    -->   Eight bits  ( = one byte )

    7  6  5  4  3  2  1  0          Bits order



        Bits N.
     =============

          7      -->  Back color intensity or Blinking
        6,5,4    -->  Back color
          3      -->  Fore color intensity
        2,1,0    -->  Fore color


  The color we specify as a string in xBase in translated -in DOS- in
  one byte. Each xBase base color is a number from 0 to 7:

             Black ......... "N"  ....... 0  ..... 0 0 0
             Blue  ......... "B"  ....... 1  ..... 0 0 1
             Green ......... "G"  ....... 2  ..... 0 1 0
             Cyan  ......... "BG" ....... 3  ..... 0 1 1      Binary
             Red   ......... "R"  ....... 4  ..... 1 0 0   representation
             Magenta ....... "RB" ....... 5  ..... 1 0 1
             Brown ......... "GR" ....... 6  ..... 1 1 0
             White ......... "W"  ....... 7  ..... 1 1 1


 In the above example, we used "W+/B" to select High intensity white letters
 on blue background. So, when we see a character with that color on screen,
 that character has an associated byte with the value:

     xBase Color           HardWare color        Binary representation
     ===========           ==============        =====================

       "W+/B"                   31                  0 0 0 1 1 1 1 1


 Lets analyze the above binary representation:

     0 0 0 1 1 1 1 1    -->    0          0 0 1        1           1 1 1

     7 6 5 4 3 2 1 0         No Back    Blue Back     Fore       White Fore
     ( bits order )         Intensity     color     Intensity       Color



 xBase Windows colors management

  Windows greatly enhances the drawing and painting capabilities of our
  applications because takes advantage of working in a graphical
  environment.

  Graphical environments offer many more colors to use: normally we will
  be using 16 or 256 colors. But we may use millions of colors (depending on
  which mode we configure Windows to work in ). Note that if you select more
  colors to use, Windows will work slower as it has to manage more memory 
  to perform the same processes.

  Graphical environments also let us use text and pictures ( Bitmaps ), 
  different fonts, brushes, etc. at the same time.

  Standard xBase language is being extended to cover all these new graphical
  environment features:

       ... COLOR <cXBASEColor>            // Standard DOS xBase color format

       ... COLOR <nRGBFore>, <nRGBBack>   // Enhanced RGB colors management

       ... BRUSH <oBrush>                 // Brushes management


  With colors, the main difference with respect DOS is that we are going
  to use RGB color formats. The RGB format is based on a LONG number ( four
  bytes ) which lets us represent millions of different colors:

                                 Four Bytes

         0                 BLUE              GREEN              RED

   X X X X X X X X    X X X X X X X X   X X X X X X X X   X X X X X X X X
   31           24   23            16  15             8   7             0

                                 Bits order

   We provide the #translate RGB() ( see Colors.ch ) to automatically
   generate RGB values:

  #translate RGB( <nRed>, <nGreen>, <nBlue> ) => ;
                ( <nRed> + ( <nGreen> * 256 ) + ( <nBlue> * 65536 ) )

  Also, FiveWin provides the function nRGB() which uses the same parameters
  and it may be called from inside your applications.

  Another very important new feature is the use of Brushes. Brushes are
  graphical Objects which automatically fill the surface of another
  Object.

  We may build Brushes from standard pure colors -which FiveWin performs
  automatically in the constructor method when we build an Object- or
  patterns based on Bitmaps.

  FiveWin easily lets us keep using the already familiar xBase color
  string format or take advantage of the use of RGB colors and
  Brush Objects.

  FiveWin uses, by default, the System colors already defined. In Windows
  to change the system colors we don't use SET COLOR TO ..., but instead
  we have to go to the Control Panel and change all the colors of the system.