This file describes the routines for managing colors in your window.
For example if you want to change what the foreground color is, or
need to get specific colors.  To get specific colors you use the
functions discussed in here.  It is important to remember that you can
not call any of these functions until you have called ShowDisplay().

Colors are represented by integers.  When you get a color, you are
returned an integer that you can use in calls to SetFgColor(),
SetBgColor(), and SetColor().  You should attach no meaning to the
numbers, and just because green is 17 does not mean that 18 is a
lighter or darker shade of green.

There are three ways to manipulate colors with libsx.  The first way
handles most of the common cases, and is done with GetNamedColor() or
GetRGBColor().

The next method, GetPrivateColor(), allows your application to modify
the actual display color represented by a color number (something you
cannot do with the the previous methods).

The final method gives you complete control in specifying the entire
colormap.  That is, you can determine exactly what integers map to
what colors so you can obtain smooth gradients (so for example black
is color 0, and white is 255).  These routines work best on 8 bit
displays but will work on 24 bit displays.

NOTE: You can NOT call any color function until you have called
      ShowDisplay(). 

-----------------------------------------------------------

The way colors work for drawing is like this.  There are usually 256
available colors on a workstation.  This is called an 8-bit display
because 2 to the 8'th power == 256.  These colors are stored in a
table (array) of 256 entries.  If you allocate a color, and it is in
entry 37, then to draw with the color that is stored there, you must
use 37 as an argument to the SetColor() function.  When you ask for a
color, it may be taken from anywhere in the array of 256 entries, and
there is _NO_ guarantee that if you allocate a green color that the
next color in the table will be a lighter or darker green.  Even if
you allocate many colors using GetNamedColor() or GetRGBColor(), you
have _NO_ assurances about where those colors are in the array
(chances are they won't be contiguous).  If you need to have a
contiguous set of numbers, you must use GetAllColors() and then
SetColorMap() or SetMyColorMap() to set up a custom colormap with a
known set of values.  When you get a private color, your application
can specify what values that color index should have.  This is useful
when you want to interactively modify a color.

It is important to remember that `getting a color' really means
getting an index into the color table where the actual color is
stored. 

If you actually want to pop up a window allowing selection of color by
users, invoke the  SelectColor  function.
It doesn't permanently allocate a color, so you show just do it with 
the other routines.

-----------------------------------------------------------
-----------------------------------------------------------

void GetStandardColors(void);

This function gets 6 standard colors, RED, GREEN, BLUE, YELLOW, BLACK,
and WHITE.  These 6 variables contain values which can be used in
calls to SetColor(), SetFgColor(), SetBgColor(), etc.  

Do not use the values in RED, GREEN, BLUE, YELLOW, BLACK or WHITE
before calling GetStandardColors().  The results are undefined if you
do this.

In addition to the above 6 standard colors, the library makes use of
3 further colors HILIGHT, BUTTONBG, INPUTBG, as follows:

HILIGHT is the color of hilighted text to be used in active
input string entries, and INPUTBG the corresponding background color.
BUTTONBG is the default color of buttons for internally defined widgets;
By default, HILIGHT coincides with the foreground color, while INPUTBG 
and BUTTONBG coincide with the background color (fg/bg default themselves
to black/white). They can be adjusted to any other color value, once such
a color has been defined through the Get*Color routines.

NOTE: You can only call GetStandardColors() after calling the
      ShowDisplay() function.

SEE ALSO : GetNamedColor(), GetRGBColor(), GetAllColors()
           SetColor(), SetFgColor(), SetBgColor()

-----------------------------------------------------------

int  GetNamedColor(char *name);

This function allocates an entry in the color table for the color
given by the ascii string "name".  You can view the list of available
color names with the showrgb command in a shell (some nice ones are
"peachpuff", "burlywood3", "aquamarine", and "paleturquoise3").  Color
names can have spaces in them.  The return value of the function is an
integer that you can use in calls to SetColor() (or any of the other
SetXXColor() calls). If an error occurred trying to allocate the color
(very possible if you allocate a lot of colors), a -1 is returned.

NOTE: the return value of zero is valid, a -1 indicates an error
      _NOT_ zero.

NOTE: You can only call GetNamedColor() after calling the
      ShowDisplay() function.

SEE ALSO : GetStandardColor(), GetRGBColor(), GetAllColors()
           SetColor(), SetFgColor(), SetBgColor()

-----------------------------------------------------------

int  GetRGBColor(int r, int g, int b);

This function tries to allocate the color given by the red, green,
blue triple r,g,b.  The arguments r,g, and b should be between 0 and
255.  Overflow is not checked for.  The return value is an integer
value usable in the SetColor() calls or a -1 if an error occurred. 

NOTE: the return value of zero is valid, a -1 indicates an error
      _NOT_ zero. 

NOTE: You can only call GetRGBColor() after calling the
      ShowDisplay() function.

SEE ALSO : GetStandardColor(), GetNamedColor(), GetAllColors()
           SetColor(), SetFgColor(), SetBgColor()

-----------------------------------------------------------
int  GetPrivateColor(void);

This function allocates a private color cell for use by the
application.  A private color cell is one which you can change what
color it represents.  For example, if you would like to let the user
interactively manipulate some color, you would need to allocate a
private color cell.

The integer returned by this function is a reference to a color cell
whose values you can set with SetPrivateColor().  The intial contents
of the private color cell are undefined and you should probably call
SetPrivateColor() immediately to set it to some known value.

If an error occurs, a -1 is returned.

When you are done with a private color cell, you should free it with
FreePrivateColor().


SEE ALSO: SetPrivateColor(), FreePrivateColor(), GetRGBColor()

-----------------------------------------------------------
void SetPrivateColor(int which, int r, int g, int b);

This function sets the color cell referred to by `which' to have the
r,g,b values specified.  The r,g,b values are given in the range 0-255
(inclusive). Once this function is called, any thing drawn in the
display with the color `which' will now have the new color determined
by the r,g,b arguments.


SEE ALSO: GetPrivateColor(), FreePrivateColor(), SetFgColor(),
          SetBgColor(), 

-----------------------------------------------------------

void FreePrivateColor(int which);

This function returns the color associated with the private color cell
`which' to the system.  You should have allocated the color referred
to by `which' with GetPrivateColor().


SEE ALSO GetPrivatecolor(), SetPrivatecolor().
-----------------------------------------------------------

int  GetAllColors(void);

This function is rather drastic and should be used with caution.  It
immediately grabs an entire 256 entry colormap for private use.  This
has the unfortunate effect of (temporarily) wiping out the colors in
all the other windows on the display.  However this is necessary if
you wish to get a smooth colormap to use in displaying a smooth-shaded
or continuous tone picture.  Once GetAllColors() is called, the entire
colormap is free for manipulation by your program.  The colormap
remains allocated until you call FreeAllColors(), at which time
everything goes back to normal.

If an error occurred (quite possible), this routine returns FALSE.  If
everything went ok and the colormap was successfully allocated, TRUE
is returned.

If you can avoid using this function, try to.  It is disconcerting for
the user to have the colormap get wacked out and have most of their
windows disappear (they don't really disappear of course, you just can
see them usually).  However it is sometimes necessary to do this as
there is no other way to get a smoothly continuous color map.

Usually, you will want to call SetColorMap() or SetMyColorMap() right
after this function. 

NOTE: On a 24 bit machine (like the SGI Indigo Elan I tested this
      with), only current drawing area gets the colormap, other
      widgets and windows are not affected.

NOTE: You can only call GetAllColors() after calling the
      ShowDisplay() function.

SEE ALSO : SetColorMap(), SetMyColorMap(), FreeAllColors(),
           GetStandardColors(), GetNamedColor(), GetRGBColor() 

-----------------------------------------------------------

void FreeAllColors(void);

This function frees a private colormap that was allocated with
GetAllColors().  It has the beneficial effect of immediately restoring
the rest of the colors on the screen and in other windows to those
that existed prior to the call to GetAllColors().  This function is
useful if wish to let the user restore their original colors
temporarily (although this will happen automatically when the mouse
moves outside the window).

-----------------------------------------------------------

void SetColorMap(int num);

This function creates several predefined color maps that are very
smoothly continuous.  It saves you the hassle of writing them yourself
(even though they are mostly easy).  The "num" argument you pass in
should be one of the following #define's : 

                #define GREY_SCALE_1    0
                #define GREY_SCALE_2    1
                #define RAINBOW_1       2
                #define RAINBOW_2       3

The colormap GREY_SCALE_2 is a complete smooth color ramp from pure
black (color 0) to pure white (color 255).  The other grey scale,
GREY_SCALE_1 is a nearly pure ramp from black (color 0) to white
(color 252), but also has a few additional colors thrown in near the
end of the colormap.  The two RAINBOW_? colormaps have different types
of smooth changing rainbows of color.  This are really only useful for
drawing pretty patterns or doing false coloring.

NOTE: You should call GetAllColors() before you call this routine.  It
is not necessary, but if you don't, and GetAllColors() fails, you will
never know about it, and your application may not work very well. 


SEE ALSO : SetMyColorMap(), GetAllColors(), GetNamedColor(),
           GetStandardColors(), GetRGBColor()

-----------------------------------------------------------

void SetMyColorMap(int n, unsigned char *r, unsigned char *g,unsigned char *b);

Occasionally it is necessary to have absolute control over your
colormap, and this function lets you do that.  This function lets you
completely specify each and every color that will be in the colormap.
The three arrays r,g, and b are simply the red, green, and blue
components of each color.  The values in the array range from 0 to
255, hence they are unsigned char's.  You need not specify a full
array of 256 colors, you can in fact only specify a few.  The integer
argument "n" indicates how many entries there are in the r,g, and b
arrays.  The argument "n" should be greater than 0 and less than 255. 

NOTE: You should call GetAllColors() before you call this routine.  It
is not necessary, but if you don't and GetAllColors() fails, you will
never know about it, and your application may not work very well. 

SEE ALSO : SetMyColorMap(), GetAllColors(), GetNamedColor(),
           GetStandardColors(), GetRGBColor()

-----------------------------------------------------------

char *SelectColor
(char *inicolor, int output, char *txt, CSelCB func, void *data);

This is a sophisticated popup which lets the user browse and select 
a color. The "mode" button cycles through 3 possible modes: RGB mode
(red-green-blue), HSV mode (hue-saturation-value), CMYK mode
(cyan-magenta-yellow-black). For each mode, the routine provides 
scrolls which the user can use to set the parameters. Meanwhile, a
rectangular draw area shows the resulting color. The user can also
browse in the RGB data file (litteral definitions of colors in
/usr/lib/X11/rgb.txt). Finally, the "Grab color" button sets the color
to be the color of any chosen pixel on the screen, and the "Best match"
button selects the predefined standard color which best approximates
the selected color. 

The parameters have the following significance: char *inicolor is the 
color to be set when the popup opens. It can be in a variety of different
formats, e.g.

  "#87CEEB"      "135,206,235"      "skyblue"      "SkyBlue"

which are viewed as equivalent denominations of the skyblue color,
whose pixel values are red=135=0x87  green=206=0xce   blue=235=0xeb
The output parameter sets which of the three forms should be used
as a return value for the char *SelectColor() procedure: 

if output=0, the returned string is in hexadecimal form "#87CEEB", 
if output=1, the returned string is either hexadecimal or litteral,
             and is litteral if there is an exact match
if output=2, the returned string is the litteral best match

The next three parameters (txt, func, data) can be used to let 
interactively the selection operate on a call-back function func.
The function is activated when the user clicks on an extra button at
the lower right corner, marked with the label char *txt. The
parameter void *data can be passed to the function. The function
func itself should be of the type

void func(Widget w, CSelData *cdata)

where cdata is a pointer to a complex structure data set, the main 
components of which are
  cdata->r cdata->g cdata->b           RGB (float values)
  cdata->h cdata->s cdata->v           HSV values
  cdata->c cdata->m cdata->y cdata->k  CMYK values
  cdata->rgb_list[1000][60]            List of litteral color names
  cdata->match_list[1000][60]          List of ordered best matches
  char *rgb_ptr[1000];                 Null terminated pointers to rgb_list
  char *match_ptr[1000];               Null terminated pointers to match_list

Finally, the initial data pointer used when invoking SelectColor can be
retrieved as  cdata->data.