Tk Library Procedures
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:
-
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. 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
Last change: 4.0
[ tcl8.0a1 | tk8.0a1 | X-ref ]
Copyright © 1989-1994 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.