- Color
- FreeAllColors
- FreePrivateColor
- GetAllColors
- GetNamedColor
- GetRGBColor
- GetPrivateColor
- GetStandardColors
- SetPrivateColor
- SetColorMap
- SetMyColorMap
- SelectColor()

## Color

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 later 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 : GetStandardColors() , 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 : GetStandardColors() , 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 machines with multiple hardware colormaps (e.g. lots of SGI machines), only the 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.