[ новости /+++ | форум | теги | ]

_________________________________________________________________

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)

     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    *)  |
                                        isn't cached.

     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_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
                         represent the most significant  bits  of
                         the  color.   For  example,  #3a7 is the
                         same as #3000a0007000.

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

     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

Партнёры:

Хостинг: