getcolor(3Tk)

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 information.  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 allocating the
     desired color, then it 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 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 procedures 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 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 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