Tk_AllocColorFromObj,   Tk_GetColor,   Tk_GetColorFromObj,
       Tk_GetColorByValue,  Tk_NameOfColor,  Tk_FreeColorFromObj,
       Tk_FreeColor - maintain database of colors


       #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_GCForColor(colorPtr, drawable)

       Tk_FreeColorFromObj(tkwin, objPtr)                         |



       Tcl_Interp   *interp     (in)      Interpreter  to use for
                                          error reporting.

       Tk_Window    tkwin       (in)      Token  for  window   in
                                          which   color  will  be

       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­

       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


       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­




       #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
                           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 |

       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­

       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­

       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.


       color, intensity, object, pixel value