Tk_AllocColorFromObj(3tk)
Tk_AllocColorFromObj(3Tk Library ProcedureTk_AllocColorFromObj(3)
_________________________________________________________________
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)
const 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
corresponding (XColor *).
char *name (in) Same as objPtr except
description of color is
passed as a string and
resulting (XColor *) is
not cached.
XColor *prefPtr (in) Indicates red, green, and
Tk Last change: 8.1 1
Tk_AllocColorFromObj(3Tk Library ProcedureTk_AllocColorFromObj(3)
blue intensities of
desired color.
XColor *colorPtr (in) Pointer to X color infor-
mation. Must have been
allocated by previous
call to
Tk_AllocColorFromObj,
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
These procedures manage the colors being used by a Tk appli-
cation. They allow colors to be shared whenever possible,
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_AllocColorFromObj
locates a pixel value that may be used to render the color
in a particular window. The desired color is specified 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 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
Tk Last change: 8.1 2
Tk_AllocColorFromObj(3Tk Library ProcedureTk_AllocColorFromObj(3)
represent the most significant bits of
the color, while the lower unfilled bits
will be repeatedly replicated from the
available higher bits. For example,
#3a7 is the same as #3333aaaa7777.
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 is not NULL.
If the colormap for tkwin is full, Tk_AllocColorFromObj will
use the closest existing color in the colormap.
Tk_AllocColorFromObj caches information about the return
value in objPtr, which speeds up future calls to procedures
such as Tk_AllocColorFromObj and Tk_GetColorFromObj.
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 cach-
ing 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 does not 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
currently in use. If the same color is requested multiple
times from Tk_GetColor or Tk_AllocColorFromObj (e.g. by dif-
ferent 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 window server, which makes the
allocation much more efficient. These procedures also pro-
vide a portable interface that works across all platforms.
For this reason, you should generally use
Tk_AllocColorFromObj, Tk_GetColor, or Tk_GetColorByValue
instead of lower level procedures like XAllocColor.
Tk Last change: 8.1 3
Tk_AllocColorFromObj(3Tk Library ProcedureTk_AllocColorFromObj(3)
Since different calls to this package 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_AllocColorFromObj or Tk_GetColor then the return value is
the string that was used 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 color is no longer needed Tk_FreeColorFromObj or
Tk_FreeColor should be called to release it. For
Tk_FreeColorFromObj 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_FreeColorFromObj or Tk_FreeColor for each call to
Tk_AllocColorFromObj, Tk_GetColor, or Tk_GetColorByValue.
KEYWORDS
color, intensity, object, pixel value
Tk Last change: 8.1 4
Man(1) output converted with
man2html