Tk_AllocColorFromObj(3) Tk Library Procedures Tk_AllocColorFromObj(3)______________________________________________________________________________NAME
Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorBy‐
Value, 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 report‐
ing.
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 *) isn't cached.
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_AllocColorFromObj,
Tk_GetColor or Tk_GetColorByValue,
except when passed to Tk_NameOf‐
Color.
Drawable drawable (in) Drawable in which the result graph‐
ics 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 possible, so that colormap │
space is preserved, and they pick closest available colors when col‐ │
ormap 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 win‐ │
dow. 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 rep‐
resent the most significant bits of the color. For
example, #3a7 is the same as #3000a0007000.
Tk_AllocColorFromObj 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 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_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 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 struc‐
ture 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 different windows), or if the same inten‐
sities 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 alloca‐
tion much more efficient. These procedures also provide 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.
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_Get‐
Color 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 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 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_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_FreeColorFro‐ │
mObj or Tk_FreeColor for each call to Tk_AllocColorFromObj, Tk_Get‐ │
Color, or Tk_GetColorByValue.
KEYWORDS
color, intensity, object, pixel value
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌────────────────────┬─────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────┤
│Availability │ SUNWTk │
├────────────────────┼─────────────────┤
│Interface Stability │ External │
└────────────────────┴─────────────────┘
NOTES
Source for Tk is available in the SUNWTkS package.
Tk 8.1 Tk_AllocColorFromObj(3)