DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tk_AllocColorFromObj(3tk)





Tk_AllocColorFromObj(3Tk Library ProcedureTk_AllocColorFromObj(3)


_________________________________________________________________


NAME

     Tk_AllocColorFromObj,    Tk_GetColor,    Tk_GetColorFromObj,
     Tk_GetColorByValue,   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)

     const 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 reporting.

     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  *) is
                                        not cached.

     XColor *prefPtr (in)               Indicates red, green, and

Tk                      Last change: 8.1                        1


Tk_AllocColorFromObj(3Tk Library ProcedureTk_AllocColorFromObj(3)


                                        blue    intensities    of
                                        desired color.

     XColor *colorPtr (in)              Pointer to X color infor-
                                        mation.   Must  have been
                                        allocated   by   previous
                                        call                   to
                                        Tk_AllocColorFromObj,
                                        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

     These procedures manage the colors being used by a Tk appli-
     cation.   They  allow colors to be shared whenever possible,
     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_AllocColorFromObj
     locates  a  pixel value that may be used to render the color
     in a particular window.  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

Tk                      Last change: 8.1                        2


Tk_AllocColorFromObj(3Tk Library ProcedureTk_AllocColorFromObj(3)


                         represent the most significant  bits  of
                         the color, while the lower unfilled bits
                         will be repeatedly replicated  from  the
                         available  higher  bits.   For  example,
                         #3a7 is the same as #3333aaaa7777.

     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 is not 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  cach-
     ing  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 does not 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 structure 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 dif-
     ferent  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
     allocation  much more efficient.  These procedures also pro-
     vide 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.

Tk                      Last change: 8.1                        3


Tk_AllocColorFromObj(3Tk Library ProcedureTk_AllocColorFromObj(3)


     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_GetColor 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 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 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_FreeColorFromObj  or  Tk_FreeColor  for  each   call   to
     Tk_AllocColorFromObj, Tk_GetColor, or Tk_GetColorByValue.


KEYWORDS

     color, intensity, object, pixel value

Tk                      Last change: 8.1                        4


Man(1) output converted with man2html