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.

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.

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

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.

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.

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() .

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.

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() .

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.

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.

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.