About Us Documentation

Contact Site Map
 

  

WinPak
Documentation

Tk_GetColorByValue





Tk_GetColor(3)        Tk Library Procedures                   4.0



_________________________________________________________________

NAME

Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor - maintain database of colors

SYNOPSIS

#include <tk.h> XColor * Tk_GetColor(interp, tkwin, nameId) XColor * Tk_GetColorByValue(tkwin, prefPtr) char * Tk_NameOfColor(colorPtr) GC Tk_GCForColor(colorPtr, drawable) 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. Tk_Uid nameId (in) Textual description of desired color. 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_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. _________________________________________________________________ Tk 1 Tk_GetColor(3) Tk Library Procedures 4.0

DESCRIPTION

The Tk_GetColor and Tk_GetColorByValue procedures locate pixel values that may be used to render particular colors in the window given by tkwin. In Tk_GetColor the desired color is specified with a Tk_Uid (nameId), which may have any 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. In Tk_GetColorByValue, the desired color is indicated with the red, green, and blue fields of the structure pointed to by colorPtr. If Tk_GetColor or Tk_GetColorByValue is successful in allo- cating the desired color, then it returns a pointer to an XColor structure; the structure indicates the exact inten- sities 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 in the color. If the colormap for tkwin is full, Tk_GetColor and Tk_GetColorByValue will use the closest existing color in the colormap. If Tk_GetColor encounters an error while allocating the color (such as an unknown color name) then NULL is returned and an error message is stored in interp- >result; Tk_GetColorByValue never returns an error. Tk_GetColor and Tk_GetColorByValue maintain a database of all the colors currently in use. If the same nameId is requested multiple times from Tk_GetColor (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 Tk 2 Tk_GetColor(3) Tk Library Procedures 4.0 interaction with the X server, which makes the allocation much more efficient. For this reason, you should generally use Tk_GetColor or Tk_GetColorByValue instead of Xlib pro- cedures like XAllocColor, XAllocNamedColor, or XParseColor. Since different calls to Tk_GetColor or Tk_GetColorByValue 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_GetColor, then the return value is the nameId string that was passed to Tk_GetColor 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 pixel value returned by Tk_GetColor or Tk_GetColorByValue is no longer needed, Tk_FreeColor should be called to release the color. There should be exactly one call to Tk_FreeColor for each call to Tk_GetColor or Tk_GetColorByValue. When a pixel value is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) Tk_FreeColor will release it to the X server and delete it from the database.

KEYWORDS

color, intensity, pixel value Tk 3 Prepared by Ready-to-Run Software, Inc.

 

Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002


To return to the Ready-to-Run Software WinPak Table of contents please presshere