Tk_GetColor(3Tk)Tk_GetColor(3Tk)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.
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:
Page 1
Tk_GetColor(3Tk)Tk_GetColor(3Tk)
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 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.
Page 2
Tk_GetColor(3Tk)Tk_GetColor(3Tk)
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
