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 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_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 application.  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 a value 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 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  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  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  a  value.   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 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  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  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  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_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 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 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, value, pixel value

Tk                                                     8.1                             Tk_AllocColorFromObj(3tk)