Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

tk_freecolorfromobj(3tk) [opensolaris man page]

Tk_AllocColorFromObj(3TK)				       Tk Library Procedures					 Tk_AllocColorFromObj(3TK)

__________________________________________________________________________________________________________________________________________________

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 *) 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 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 win- dow 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 repre- sents 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 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 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 proce- | dures 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 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 | 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 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 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 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_GetColor then the return value is the string that was used to create the color. If colorPtr was created by a call to Tk_GetColorBy- Value, 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 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_AllocColorFromObj, Tk_Get- | Color, or Tk_GetColorByValue. KEYWORDS
color, intensity, object, pixel value ATTRIBUTES
See attributes(5) for descriptions of the following attributes: +--------------------+-----------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +--------------------+-----------------+ |Availability | SUNWTk | +--------------------+-----------------+ |Interface Stability | Uncommitted | +--------------------+-----------------+ NOTES
Source for Tk is available on http://opensolaris.org. Tk 8.1 Tk_AllocColorFromObj(3TK)
Man Page