tk4.2 C API - GetColor






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 infor-
                                        mation.   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  allo-
     cating  the  desired  color, then it returns a pointer to an
     XColor structure;  the structure indicates the exact  inten-
     sities  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  pro-
     cedures 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 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   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