NAME
Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj,
Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj,
Tk_FreeColor - maintain database of colors
SYNOPSIS
#include <tk.h>
XColor * |
Tk_AllocColorFromObj(interp, tkwin, objPtr) |
XColor * |
Tk_GetColor(interp, tkwin, name) |
XColor * |
Tk_GetColorFromObj(tkwin, objPtr) |
XColor *
Tk_GetColorByValue(tkwin, prefPtr)
char *
Tk_NameOfColor(colorPtr)
GC
Tk_GCForColor(colorPtr, drawable)
Tk_FreeColorFromObj(tkwin, objPtr) |
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.
Tcl_Obj *objPtr (in/out) ||
String value describes |
desired color; internal |
rep will be modified to |
cache pointer to corre |
sponding (XColor *). |
char *name (in) ||
Same as objPtr except |
description of color is |
passed as a string and |
resulting (XColor *) |
isn't cached.
and blue intensities of
desired color.
XColor *colorPtr (in) Pointer to X color
information. Must have
been allocated by pre
vious call to Tk_Alloc
ColorFromObj, Tk_Get
Color or Tk_GetColorBy
Value, except when
passed to Tk_NameOf
Color.
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
These procedures manage the colors being used by a Tk |
application. They allow colors to be shared whenever pos |
sible, so that colormap space is preserved, and they pick |
closest available colors when colormap space is exhausted. |
Given a textual description of a color, Tk_AllocColorFro |
mObj locates a pixel value that may be used to render the |
color in a particular window. The desired color is speci |
fied with an object whose string value must have one 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 Peach
Puff.
#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
represent the most significant bits of
the color. For example, #3a7 is the
same as #3000a0007000.
Tk_AllocColorFromObj returns a pointer to an XColor struc |
ture; 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 with the color in |
tkwin. If an error occurs in Tk_AllocColorFromObj (such |
as an unknown color name) then NULL is returned and an |
error message is stored in interp's result if interp isn't |
NULL. If the colormap for tkwin is full, Tk_AllocColor |
FromObj will use the closest existing color in the col |
ormap. Tk_AllocColorFromObj caches information about the |
return value in objPtr, which speeds up future calls to |
procedures such as Tk_AllocColorFromObj and Tk_GetColor |
FromObj. |
Tk_GetColor is identical to Tk_AllocColorFromObj except |
that the description of the color is specified with a |
string instead of an object. This prevents Tk_GetColor |
from caching the return value, so Tk_GetColor is less |
efficient than Tk_AllocColorFromObj. |
Tk_GetColorFromObj returns the token for an existing |
color, given the window and description used to create the |
color. Tk_GetColorFromObj doesn't actually create the |
color; the color must already have been created with a |
previous call to Tk_AllocColorFromObj or Tk_GetColor. The |
return value is cached in objPtr, which speeds up future |
calls to Tk_GetColorFromObj with the same objPtr and |
tkwin.
Tk_GetColorByValue is similar to Tk_GetColor except that
the desired color is indicated with the red, green, and
blue fields of the structure pointed to by colorPtr.
This package maintains a database of all the colors cur
rently in use. If the same color is requested multiple
times from Tk_GetColor or Tk_AllocColorFromObj (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 exist
ing pixel avoids any interaction with the window server,
which makes the allocation much more efficient. These
procedures also provide a portable interface that works
across all platforms. For this reason, you should gener
ally use Tk_AllocColorFromObj, Tk_GetColor, or Tk_GetCol
orByValue instead of lower level procedures like XAlloc
Color.
Since different calls to this package may return the same
of a pixel returned by the procedures. If you need to
change a color value dynamically, you should use XAlloc
ColorCells 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_AllocColorFromObj or Tk_GetColor then the return value
is the string that was used to create the color. If col
orPtr 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_Name
OfColor.
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 col
orPtr exists; it is freed when the last reference to col
orPtr is freed by calling Tk_FreeColor.
When a color is no longer needed Tk_FreeColorFromObj or |
Tk_FreeColor should be called to release it. For Tk_Free |
ColorFromObj the color to release is specified with the |
same information used to create it; for Tk_FreeColor the |
color to release is specified with a pointer to its XColor |
structure. There should be exactly one call to Tk_Free |
ColorFromObj or Tk_FreeColor for each call to Tk_AllocCol |
orFromObj, Tk_GetColor, or Tk_GetColorByValue.
KEYWORDS
color, intensity, object, pixel value
Man(1) output converted with
man2html