Tk_GetColor(3) Tk (4.0) Tk_GetColor(3)
_________________________________________________________________
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
information. 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.
Page 1 (printed 2/26/99)
Tk_GetColor(3) Tk (4.0) Tk_GetColor(3)
_________________________________________________________________
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
allocating the desired color, then it returns a pointer to
an XColor structure; the structure indicates the exact
intensities 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
Page 2 (printed 2/26/99)
Tk_GetColor(3) Tk (4.0) Tk_GetColor(3)
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
procedures 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
persist 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
Page 3 (printed 2/26/99)
