TkAllocColorFromObj(3) Tk Library Procedures TkAllocColorFromObj(3)

NAME
       TkAllocColorFromObj,  TkGetColor,  TkGetColorFromObj, TkGetColorBy-
       Value, TkNameOfColor,  TkFreeColorFromObj,  TkFreeColor  -  maintain
       database of colors

SYNOPSIS
       ##iinncclluuddee <>

       XColor *                                                                |
       TTkkAAllllooccCCoolloorrFFrroommOObbjj((interp, tkwin, objPtr))                             |

       XColor *                                                                |
       TTkkGGeettCCoolloorr((interp, tkwin, name))                                        |

       XColor *                                                                |
       TTkkGGeettCCoolloorrFFrroommOObbjj((tkwin, objPtr))                                       |

       XColor *
       TTkkGGeettCCoolloorrBByyVVaalluuee((tkwin, prefPtr))

       CONST char *
       TTkkNNaammeeOOffCCoolloorr((colorPtr))

       GC
       TTkkGGCCFFoorrCCoolloorr((colorPtr, drawable))

       TTkkFFrreeeeCCoolloorrFFrroommOObbjj((tkwin, objPtr))                                      |

       TTkkFFrreeeeCCoolloorr((colorPtr))

AARRGGUUMMEENNTTSS
       TclInterp   *interp     (in)      Interpreter to use for error report-
                                          ing.

       TkWindow    tkwin       (in)      Token for window in which color will
                                          be used.

       TclObj      *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    TTkkAAllllooccCCoolloorrFFrroommOObbjj,
                                          TTkkGGeettCCoolloorr  or  TTkkGGeettCCoolloorrBByyVVaalluuee,
                                          except  when  passed  to  TTkkNNaammeeOOff-
                                          CCoolloorr.

       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, TTkkAAllllooccCCoolloorrFFrroommOObbjj 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 rreedd or
                           PPeeaacchhPPuuffff.

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

       TTkkAAllllooccCCoolloorrFFrroommOObbjj 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 TTkkAAllllooccCCoolloorrFFrroommOObbjj (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, TTkkAAllllooccCCoolloorrFFrroommOObbjj will use the closest existing color |
       in the colormap.  TTkkAAllllooccCCoolloorrFFrroommOObbjj  caches  information  about  the |
       return value in objPtr, which speeds up future calls to procedures such |
       as TTkkAAllllooccCCoolloorrFFrroommOObbjj and TTkkGGeettCCoolloorrFFrroommOObbjj.                         |

       TTkkGGeettCCoolloorr  is  identical  to  TTkkAAllllooccCCoolloorrFFrroommOObbjj  except  that  the |
       description  of  the  color  is  specified  with a string instead of an |
       object.  This prevents TTkkGGeettCCoolloorr from caching the  return  value,  so |
       TTkkGGeettCCoolloorr is less efficient than TTkkAAllllooccCCoolloorrFFrroommOObbjj.                |

       TTkkGGeettCCoolloorrFFrroommOObbjj  returns  the token for an existing color, given the |
       window and description used to create  the  color.   TTkkGGeettCCoolloorrFFrroommOObbjj |
       doesn't  actually  create  the  color; the color must already have been |
       created with a previous call to  TTkkAAllllooccCCoolloorrFFrroommOObbjj  or  TTkkGGeettCCoolloorr. |
       The  return  value is cached in objPtr, which speeds up future calls to |
       TTkkGGeettCCoolloorrFFrroommOObbjj with the same objPtr and tkwin.

       TTkkGGeettCCoolloorrBByyVVaalluuee is similar to TTkkGGeettCCoolloorr 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 TTkkGGeettCCoolloorr or
       TTkkAAllllooccCCoolloorrFFrroommOObbjj (e.g. by different windows), or if the same inten-
       sities  are  requested  multiple  times  from  TTkkGGeettCCoolloorrBByyVVaalluuee, 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 TTkkAAllllooccCCoolloorrFFrroommOObbjj, TTkkGGeettCCoolloorr, or  TTkkGGeettCCoolloorrBByyVVaalluuee
       instead of lower level procedures like XXAAllllooccCCoolloorr.

       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 XXAAllllooccCCoolloorrCCeellllss to allocate the pixel value for the  color.

       The procedure TTkkNNaammeeOOffCCoolloorr is roughly the inverse of TTkkGGeettCCoolloorr.  If
       its colorPtr argument was created by  TTkkAAllllooccCCoolloorrFFrroommOObbjj  or  TTkkGGeett-
       CCoolloorr  then  the return value is the string that was used to create the
       color.  If colorPtr was created by a call to TTkkGGeettCCoolloorrBByyVVaalluuee, or  by
       any  other  mechanism,  then the return value is a string that could be
       passed to TTkkGGeettCCoolloorr to return the  same  color.   Note:   the  string
       returned by TTkkNNaammeeOOffCCoolloorr is only guaranteed to persist until the next
       call to TTkkNNaammeeOOffCCoolloorr.

       TTkkGGCCFFoorrCCoolloorr returns a graphics context whose ffoorreeggrroouunndd 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 TTkkFFrreeeeCCoolloorr.

       When  a  color  is no longer needed TTkkFFrreeeeCCoolloorrFFrroommOObbjj or TTkkFFrreeeeCCoolloorr |
       should be called to release it.  For TTkkFFrreeeeCCoolloorrFFrroommOObbjj the  color  to |
       release  is  specified with the same information used to create it; for |
       TTkkFFrreeeeCCoolloorr the color to release is specified with a  pointer  to  its |
       XColor structure.  There should be exactly one call to TTkkFFrreeeeCCoolloorrFFrroo- |
       mmOObbjj or TTkkFFrreeeeCCoolloorr for each  call  to  TTkkAAllllooccCCoolloorrFFrroommOObbjj,  TTkkGGeett- |
       CCoolloorr, or TTkkGGeettCCoolloorrBByyVVaalluuee.

KKEEYYWWOORRDDSS
       color, intensity, object, pixel value



Tk                                    8.1              TkAllocColorFromObj(3)