diff options
author | rjohnson <rjohnson> | 1998-04-01 09:37:39 (GMT) |
---|---|---|
committer | rjohnson <rjohnson> | 1998-04-01 09:37:39 (GMT) |
commit | 13242623d2ff3ea02ab6a62bfb48a7dbb5c27e22 (patch) | |
tree | 3100714738a7941b590efee466a774862f9671c3 /doc/GetColor.3 | |
parent | e4ab1102029f9ac557ff190bfb9d34408340f345 (diff) | |
download | tk-13242623d2ff3ea02ab6a62bfb48a7dbb5c27e22.zip tk-13242623d2ff3ea02ab6a62bfb48a7dbb5c27e22.tar.gz tk-13242623d2ff3ea02ab6a62bfb48a7dbb5c27e22.tar.bz2 |
Initial revision
Diffstat (limited to 'doc/GetColor.3')
-rw-r--r-- | doc/GetColor.3 | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/doc/GetColor.3 b/doc/GetColor.3 new file mode 100644 index 0000000..7f89446 --- /dev/null +++ b/doc/GetColor.3 @@ -0,0 +1,146 @@ +'\" +'\" Copyright (c) 1990, 1991 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetColor.3 1.22 96/08/27 13:21:26 +'\" +.so man.macros +.TH Tk_GetColor 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor \- maintain database of colors +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +XColor * +\fBTk_GetColor\fR(\fIinterp, tkwin, nameId\fB)\fR +.sp +XColor * +\fBTk_GetColorByValue\fR(\fItkwin, prefPtr\fB)\fR +.sp +char * +\fBTk_NameOfColor(\fIcolorPtr\fB)\fR +.sp +GC +\fBTk_GCForColor\fR(\fIcolorPtr, drawable\fR) +.sp +\fBTk_FreeColor(\fIcolorPtr\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *colorPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window in which color will be used. +.AP Tk_Uid nameId in +Textual description of desired color. +.AP XColor *prefPtr in +Indicates red, green, and blue intensities of desired +color. +.AP XColor *colorPtr in +Pointer to X color information. Must have been allocated by previous +call to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR, except when passed +to \fBTk_NameOfColor\fR. +.AP 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. +.BE + +.SH DESCRIPTION +.PP +The \fBTk_GetColor\fR and \fBTk_GetColorByValue\fR procedures +locate pixel values that may be used to render particular +colors in the window given by \fItkwin\fR. In \fBTk_GetColor\fR +the desired color is specified with a Tk_Uid (\fInameId\fR), which +may have any of the following forms: +.TP 20 +\fIcolorname\fR +Any of the valid textual names for a color defined in the +server's color database file, such as \fBred\fR or \fBPeachPuff\fR. +.TP 20 +\fB#\fIRGB\fR +.TP 20 +\fB#\fIRRGGBB\fR +.TP 20 +\fB#\fIRRRGGGBBB\fR +.TP 20 +\fB#\fIRRRRGGGGBBBB\fR +A numeric specification of the red, green, and blue intensities +to use to display the color. Each \fIR\fR, \fIG\fR, or \fIB\fR +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. +.PP +In \fBTk_GetColorByValue\fR, the desired color is indicated with +the \fIred\fR, \fIgreen\fR, and \fIblue\fR fields of the structure +pointed to by \fIcolorPtr\fR. +.PP +If \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR is successful +in allocating the desired color, then it 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 in the color. +If the colormap for \fItkwin\fR is full, \fBTk_GetColor\fR +and \fBTk_GetColorByValue\fR will use the closest existing color +in the colormap. +If \fBTk_GetColor\fR encounters an error while allocating +the color (such as an unknown color name) then NULL is returned and +an error message is stored in \fIinterp->result\fR; +\fBTk_GetColorByValue\fR never returns an error. +.PP +\fBTk_GetColor\fR and \fBTk_GetColorByValue\fR maintain a database +of all the colors currently in use. +If the same \fInameId\fR is requested multiple times from +\fBTk_GetColor\fR (e.g. by different windows), or if the +same intensities are requested multiple times from +\fBTk_GetColorByValue\fR, then existing pixel values will +be re-used. Re-using an existing pixel avoids any interaction +with the X server, which makes the allocation much more +efficient. For this reason, you should generally use +\fBTk_GetColor\fR or \fBTk_GetColorByValue\fR +instead of Xlib procedures like \fBXAllocColor\fR, +\fBXAllocNamedColor\fR, or \fBXParseColor\fR. +.PP +Since different calls to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR +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 +\fBXAllocColorCells\fR to allocate the pixel value for the color. +.PP +The procedure \fBTk_NameOfColor\fR is roughly the inverse of +\fBTk_GetColor\fR. If its \fIcolorPtr\fR argument was created +by \fBTk_GetColor\fR, then the return value is the \fInameId\fR +string that was passed to \fBTk_GetColor\fR to create the +color. If \fIcolorPtr\fR was created by a call to \fBTk_GetColorByValue\fR, +or by any other mechanism, then the return value is a string +that could be passed to \fBTk_GetColor\fR to return the same +color. Note: the string returned by \fBTk_NameOfColor\fR is +only guaranteed to persist until the next call to \fBTk_NameOfColor\fR. +.PP +\fBTk_GCForColor\fR returns a graphics context whose \fBForeground\fR +field is the pixel allocated for \fIcolorPtr\fR 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 \fIcolorPtr\fR exists; it is freed when the last reference +to \fIcolorPtr\fR is freed by calling \fBTk_FreeColor\fR. +.PP +When a pixel value returned by \fBTk_GetColor\fR or +\fBTk_GetColorByValue\fR is no longer +needed, \fBTk_FreeColor\fR should be called to release the color. +There should be exactly one call to \fBTk_FreeColor\fR for +each call to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR. +When a pixel value is no longer in +use anywhere (i.e. it has been freed as many times as it has been gotten) +\fBTk_FreeColor\fR will release it to the X server and delete it from +the database. + +.SH KEYWORDS +color, intensity, pixel value |