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) CONST char * Tk_NameOfColor(colorPtr) GC Tk_GCForColor(colorPtr, drawable) Tk_FreeColorFromObj(tkwin, objPtr) | Tk_FreeColor(colorPtr) ARGUMENTS Tcl_Interp *interp (in(1,8)) Interpreter to use for error(8,n) report- ing. Tk_Window tkwin (in(1,8)) Token for window in(1,8) which color will be used. Tcl_Obj *objPtr (in(1,8)/out) || String value describes desired | color; internal rep will be modified | to cache pointer to corresponding | (XColor *). | char *name (in(1,8)) || Same as objPtr except description of | color is passed as a string(3,n) and | resulting (XColor *) isn't cached. XColor *prefPtr (in(1,8)) Indicates red, green, and blue intensities of desired color. XColor *colorPtr (in(1,8)) 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(1,8)) Drawable in(1,8) 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(1,8) a particular win- | dow. The desired color is specified with an object whose string(3,n) value | must have one of the following forms: colorname Any of the valid textual names for a color defined in(1,8) the server's color database file(1,n), 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(1,8) tkwin. If an error(8,n) occurs in(1,8) Tk_AllocColorFromObj (such as an | unknown color name) then NULL is returned and an error(8,n) message is | stored in(1,8) interp's result if(3,n) interp isn't NULL. If the colormap for | tkwin is full, Tk_AllocColorFromObj will use the closest existing color | in(1,8) the colormap. Tk_AllocColorFromObj caches information about the | return value in(1,8) 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(3,n) instead of an | object. This prevents Tk_GetColor from caching the return value, so | Tk_GetColor is less(1,3) 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(1,8) 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(1,8) use. If the same color is requested multiple times from Tk_GetColor or Tk_AllocColorFromObj (e.g. by different windows), or if(3,n) the same inten- sities 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(3,n) 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(3,n) that could be passed to Tk_GetColor to return the same color. Note: the string(3,n) 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)