tk4.2 C API - GetColor
NAME
Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor,
Tk_FreeColor - maintain database of colors
SYNOPSIS
#include <tk.h>
XColor *
Tk_GetColor(interp, tkwin, nameId)
XColor *
Tk_GetColorByValue(tkwin, prefPtr)
char *
Tk_NameOfColor(colorPtr)
GC
Tk_GCForColor(colorPtr, drawable)
Tk_FreeColor(colorPtr)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter to use for
error reporting.
Tk_Window tkwin (in) Token for window in which
color will be used.
Tk_Uid nameId (in) Textual description of
desired color.
XColor *prefPtr (in) Indicates red, green, and
blue intensities of
desired color.
XColor *colorPtr (in) Pointer to X color infor-
mation. Must have been
allocated by previous
call to Tk_GetColor or
Tk_GetColorByValue,
except when passed to
Tk_NameOfColor.
Drawable drawable (in) Drawable in which the
result graphics context
will be used. Must have
same screen and depth as
the window for which the
color was allocated.
DESCRIPTION
The Tk_GetColor and Tk_GetColorByValue procedures locate
pixel values that may be used to render particular colors in
the window given by tkwin. In Tk_GetColor the desired color
is specified with a Tk_Uid (nameId), which may have any of
the following forms:
colorname Any of the valid textual names for a
color defined in the server's color
database file, such as red or PeachPuff.
#RGB
#RRGGBB
#RRRGGGBBB
#RRRRGGGGBBBB A numeric specification of the red,
green, and blue intensities to use to
display the color. Each R, G, or B
represents a single hexadecimal digit.
The four forms permit colors to be
specified with 4-bit, 8-bit, 12-bit or
16-bit values. When fewer than 16 bits
are provided for each color, they
represent the most significant bits of
the color. For example, #3a7 is the
same as #3000a0007000.
In Tk_GetColorByValue, the desired color is indicated with
the red, green, and blue fields of the structure pointed to
by colorPtr.
If Tk_GetColor or Tk_GetColorByValue is successful in allo-
cating the desired color, then it returns a pointer to an
XColor structure; the structure indicates the exact inten-
sities of the allocated color (which may differ slightly
from those requested, depending on the limitations of the
screen) and a pixel value that may be used to draw in the
color. If the colormap for tkwin is full, Tk_GetColor and
Tk_GetColorByValue will use the closest existing color in
the colormap. If Tk_GetColor encounters an error while
allocating the color (such as an unknown color name) then
NULL is returned and an error message is stored in interp-
>result; Tk_GetColorByValue never returns an error.
Tk_GetColor and Tk_GetColorByValue maintain a database of
all the colors currently in use. If the same nameId is
requested multiple times from Tk_GetColor (e.g. by different
windows), or if the same intensities are requested multiple
times from Tk_GetColorByValue, then existing pixel values
will be re-used. Re-using an existing pixel avoids any
interaction with the X server, which makes the allocation
much more efficient. For this reason, you should generally
use Tk_GetColor or Tk_GetColorByValue instead of Xlib pro-
cedures like XAllocColor, XAllocNamedColor, or XParseColor.
Since different calls to Tk_GetColor or Tk_GetColorByValue
may return the same shared pixel value, callers should never
change the color of a pixel returned by the procedures. If
you need to change a color value dynamically, you should use
XAllocColorCells to allocate the pixel value for the color.
The procedure Tk_NameOfColor is roughly the inverse of
Tk_GetColor. If its colorPtr argument was created by
Tk_GetColor, then the return value is the nameId string that
was passed to Tk_GetColor to create the color. If colorPtr
was created by a call to Tk_GetColorByValue, or by any other
mechanism, then the return value is a string that could be
passed to Tk_GetColor to return the same color. Note: the
string returned by Tk_NameOfColor is only guaranteed to per-
sist until the next call to Tk_NameOfColor.
Tk_GCForColor returns a graphics context whose Foreground
field is the pixel allocated for colorPtr and whose other
fields all have default values. This provides an easy way
to do basic drawing with a color. The graphics context is
cached with the color and will exist only as long as
colorPtr exists; it is freed when the last reference to
colorPtr is freed by calling Tk_FreeColor.
When a pixel value returned by Tk_GetColor or
Tk_GetColorByValue is no longer needed, Tk_FreeColor should
be called to release the color. There should be exactly one
call to Tk_FreeColor for each call to Tk_GetColor or
Tk_GetColorByValue. When a pixel value is no longer in use
anywhere (i.e. it has been freed as many times as it has
been gotten) Tk_FreeColor will release it to the X server
and delete it from the database.
KEYWORDS
color, intensity, pixel value