ABCDEFGHIJKLMNOPQRSTUVWXYZ

Tk_GetColor

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



Tk                                    8.1              Tk_AllocColorFromObj(3)