Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tk_AllocColorFromObj(3)                     Tk Library Procedures                    Tk_AllocColorFromObj(3)



____________________________________________________________________________________________________________

NAME
       Tk_AllocColorFromObj,  Tk_GetColor,  Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_Free-ColorFromObj, Tk_FreeColorFromObj,
       ColorFromObj, 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  modi-fied modified
                                          fied 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 blue intensities of desired color.

       XColor *colorPtr (in)              Pointer to X color information.  Must have been allocated by  pre-vious previous
                                          vious  call to Tk_AllocColorFromObj, Tk_GetColor or Tk_GetColorBy-Value, Tk_GetColorByValue,
                                          Value, 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 application.  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 sig-nificant significant
                           nificant 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 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  speci-fied specified
       fied 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 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 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
       allocation 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 dynami-cally, dynamically,
       cally, 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  mecha-nism, mechanism,
       nism, 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 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_AllocColorFro-mObj, Tk_AllocColorFromObj,
       mObj, Tk_GetColor, or Tk_GetColorByValue.

KEYWORDS
       color, intensity, object, pixel value



Tk                                                   8.1                             Tk_AllocColorFromObj(3)