# vColor

A class for handling and specifying colors.

## Synopsis

Header:
  `<v/vcolor.h>`
Class name:
  vColor

## Description

The V color model allows you to specify colors as an RGB value. The intensity of each primary color, red, green, and blue are specified as a value between 0 and 255. This allows you to specify up to 224 colors. Just how many of all these colors you can see and how they will look on your display will depend on that display. Even so, you can probably count on (255,0,0) being something close to red on most displays. Given this 24 bit model, the `vColor` class allows you to define colors easily.

In order to make using colors somewhat easier, V has defined a standard array of 16 basic colors that you can access by including `v/vcolor.h>`. This array is called `vStdColors`. You index the array using the symbols `vC_Black`, `vC_Red`, `vC_DimRed`, `vC_Green`, `vC_DimGreen`, `vC_Blue`, `vC_DimBlue`, `vC_Yellow`, `vC_DimYellow`, `vC_Magenta`, `vC_DimMagenta`, `vC_Cyan`, `vC_DimCyan`, `vC_DarkGray`, `vC_MedGray`, and `vC_White`. For example, use the standard color `vStdColors[vC_Green]` to represent green. You can also get a `char` for the color by using the symbol to index the `char* vColorName[16]` array.

The file `<v/vcb2x4.h>` contains definitions for 8 color buttons in a 2 high by 4 wide frame. The file `<v/vcb2x8.h>` has a 2 by 8 frame of all 16 standard colors. You can specify the size of each button in the frame by defining `vC_Size`. The default is 8. You can also specify the location in a dialog of the color button frame by defining the symbols `vC_Frame, vC_RightOf,` and `vC_Below`. The ids of each button in the frame correspond to the color indexes, but with a `M` prefix (e.g., `M_Red` for `vC_Red`). See the example in `v/examp` for and example of using the standard color button frames.

Also note that unlike most other V objects, it makes perfect sense to assign and copy `vColor` values. Thus, assignment, copy constructor, and equality comparison operators are provided.

## Constructor

#### vColor(unsigned int rd 0, unsigned int gr = 0, unsigned int bl = 0)

The class has been defined so you can easily initialize a color either by using its constructor directly, or indirectly via an array declaration. Each color has a red, green, and blue value in the range of 0 to 255.

      // Declare Red via constructor
      vColor btncolor(255, 0 , 0);   // Red

      // Declare array with green and blue
      vColor GreenAndBlue[2] =
        {
          (0, 255, 0),              // Green
          (0, 0, 255)               // Blue
        };

## Utility Methods

#### BitsOfColor()

This method returns the number of bits used by the machine to display to represent color. A value of 8, for example, means the computer is using 8 bits to show the color.

#### ResetColor(unsigned int rd = 0, unsigned int gr = 0, unsigned int bl = 0)

#### ResetColor(vColor& c)

Like the `Set` method, this method will set all three values of the color at once. However, V tries to preserve entries in the system color palette or color map with `ResetColor`. You can also pass a `vColor` object.

Consider the following code excerpt:

        vColor aColor;        // A V Color
        vBrush aBrush;
        int iy;

        ...

        for (iy = 0 ; iy < 128 ; ++iy)
          {
            aColor.Set(iy,iy,iy);     // Set to shade of gray
            aBrush.SetColor(aColor);  // Set brush
            canvas.DrawLine(10,iy+100,200,iy+100);  // Draw line
          }
        ...

This example will use up 128 color map entries on some systems (X, for example). Once a system has run out of entries, V will draw in black or white. When these systems run out of new color map entries, the color drawn for new colors will be black or white.

        vColor aColor;        // A V Color
        vBrush aBrush;
        int iy;

        ...

        for (iy = 0 ; iy < 128 ; ++iy)
          {
            aColor.ResetColor(iy,iy,iy);     // Set to shade of gray
            aBrush.SetColor(aColor);  // Set brush
            canvas.DrawLine(10,iy+100,200,iy+100);  // Draw line
          }
        ...

This example accomplishes the same as the first, but does not use up color map entries. Instead, the entry used for `aColor` is reused to get better use of the color map. If your application will be working with a large number of colors that will vary, using `ResetColor` will minimize the number of color map accesses.

On some systems, and systems with a full 24 bits of color, `ResetColor` and `Set` work identically.

WARNING: If you intend to use `ResetColor` on a `vColor` object, then `ResetColor` is the only way you should change the color of that object. You should not use the color assignment operator, or `Set`. `ResetColor` needs to do some unconventional things internally to preserve color palette entries, and these can be incompatible with regular assignment or `Set`. You can, however, safely use such a `vColor` object with any other `vColor` object. For example:

        vColor c1, c2;

        c1.ResetColor(100,100,100);    // You can use c1 with others.
        c2 = c1;                       // OK, but this = now makes c2
                                       // incompatible with ResetColor.
        c2.ResetColor(200,200,200);    // DON'T DO THIS

#### Set(unsigned int rd = 0, unsigned int gr = 0, unsigned int bl = 0)

Set all three values of the color at once.

#### void SetR(unsigned int rd = 0)

Set the Red value.

#### void SetG(unsigned int gr = 0)

Set the Green value.

#### void SetB(unsigned int bl = 0)

Set the Blue value.

#### unsigned int r()

Get the Red value.

#### unsigned int g()

Get the Green value.

#### unsigned int b()

Get the Blue value.

#### int operator ==

Compare two color objects for equality.

#### int operator !=

Compare two color objects for inequality.

## Notes about color

The color model used by V attempts to hide most of the details for using color. However, for some applications you may end up confronting some of the sticky issues of color.

Most machines in use in 1996 will not support all 224 colors that can be represented by the RGB color specification. Typically, they devote 8 or 16 bits to each pixel. This means that the 24-bit RGB colors must be mapped to the smaller 8-bit or 16-bit range. This mapping is usually accomplished by using a palette or colormap.

V tries to use the default system color palette provided by the machine it is running on. On some systems, such as X, it is possible to run out of entries in the color map. Others, like Windows, map colors not in the color palette to dithered colors. V provides two methods to help with this problem. First, `vColor::BitsOfColor()` tells you how many bits are used by the running system to represent color. The method `vColor::ResetColor(r,g,b)` can be used to change the value of a color without using up another entry in the system color map. For now, these methods should allow you to work with color with pretty good flexibility. Eventually, V may include more direct support for color palettes.

## See Also

C_ColorButton, vCanvas