| 1 |
578 |
markom |
'\"
|
| 2 |
|
|
'\" Copyright (c) 1990, 1991 The Regents of the University of California.
|
| 3 |
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
| 4 |
|
|
'\"
|
| 5 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
| 6 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
| 7 |
|
|
'\"
|
| 8 |
|
|
'\" RCS: @(#) $Id: GetColor.3,v 1.1.1.1 2002-01-16 10:25:48 markom Exp $
|
| 9 |
|
|
'\"
|
| 10 |
|
|
.so man.macros
|
| 11 |
|
|
.TH Tk_GetColor 3 4.0 Tk "Tk Library Procedures"
|
| 12 |
|
|
.BS
|
| 13 |
|
|
.SH NAME
|
| 14 |
|
|
Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor \- maintain database of colors
|
| 15 |
|
|
.SH SYNOPSIS
|
| 16 |
|
|
.nf
|
| 17 |
|
|
\fB#include \fR
|
| 18 |
|
|
.sp
|
| 19 |
|
|
XColor *
|
| 20 |
|
|
\fBTk_GetColor\fR(\fIinterp, tkwin, nameId\fB)\fR
|
| 21 |
|
|
.sp
|
| 22 |
|
|
XColor *
|
| 23 |
|
|
\fBTk_GetColorByValue\fR(\fItkwin, prefPtr\fB)\fR
|
| 24 |
|
|
.sp
|
| 25 |
|
|
char *
|
| 26 |
|
|
\fBTk_NameOfColor(\fIcolorPtr\fB)\fR
|
| 27 |
|
|
.sp
|
| 28 |
|
|
GC
|
| 29 |
|
|
\fBTk_GCForColor\fR(\fIcolorPtr, drawable\fR)
|
| 30 |
|
|
.sp
|
| 31 |
|
|
\fBTk_FreeColor(\fIcolorPtr\fB)\fR
|
| 32 |
|
|
.SH ARGUMENTS
|
| 33 |
|
|
.AS "Tcl_Interp" *colorPtr
|
| 34 |
|
|
.AP Tcl_Interp *interp in
|
| 35 |
|
|
Interpreter to use for error reporting.
|
| 36 |
|
|
.AP Tk_Window tkwin in
|
| 37 |
|
|
Token for window in which color will be used.
|
| 38 |
|
|
.AP Tk_Uid nameId in
|
| 39 |
|
|
Textual description of desired color.
|
| 40 |
|
|
.AP XColor *prefPtr in
|
| 41 |
|
|
Indicates red, green, and blue intensities of desired
|
| 42 |
|
|
color.
|
| 43 |
|
|
.AP XColor *colorPtr in
|
| 44 |
|
|
Pointer to X color information. Must have been allocated by previous
|
| 45 |
|
|
call to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR, except when passed
|
| 46 |
|
|
to \fBTk_NameOfColor\fR.
|
| 47 |
|
|
.AP Drawable drawable in
|
| 48 |
|
|
Drawable in which the result graphics context will be used. Must have
|
| 49 |
|
|
same screen and depth as the window for which the color was allocated.
|
| 50 |
|
|
.BE
|
| 51 |
|
|
|
| 52 |
|
|
.SH DESCRIPTION
|
| 53 |
|
|
.PP
|
| 54 |
|
|
The \fBTk_GetColor\fR and \fBTk_GetColorByValue\fR procedures
|
| 55 |
|
|
locate pixel values that may be used to render particular
|
| 56 |
|
|
colors in the window given by \fItkwin\fR. In \fBTk_GetColor\fR
|
| 57 |
|
|
the desired color is specified with a Tk_Uid (\fInameId\fR), which
|
| 58 |
|
|
may have any of the following forms:
|
| 59 |
|
|
.TP 20
|
| 60 |
|
|
\fIcolorname\fR
|
| 61 |
|
|
Any of the valid textual names for a color defined in the
|
| 62 |
|
|
server's color database file, such as \fBred\fR or \fBPeachPuff\fR.
|
| 63 |
|
|
.TP 20
|
| 64 |
|
|
\fB#\fIRGB\fR
|
| 65 |
|
|
.TP 20
|
| 66 |
|
|
\fB#\fIRRGGBB\fR
|
| 67 |
|
|
.TP 20
|
| 68 |
|
|
\fB#\fIRRRGGGBBB\fR
|
| 69 |
|
|
.TP 20
|
| 70 |
|
|
\fB#\fIRRRRGGGGBBBB\fR
|
| 71 |
|
|
A numeric specification of the red, green, and blue intensities
|
| 72 |
|
|
to use to display the color. Each \fIR\fR, \fIG\fR, or \fIB\fR
|
| 73 |
|
|
represents a single hexadecimal digit. The four forms permit
|
| 74 |
|
|
colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values.
|
| 75 |
|
|
When fewer than 16 bits are provided for each color, they represent
|
| 76 |
|
|
the most significant bits of the color. For example, #3a7 is the
|
| 77 |
|
|
same as #3000a0007000.
|
| 78 |
|
|
.PP
|
| 79 |
|
|
In \fBTk_GetColorByValue\fR, the desired color is indicated with
|
| 80 |
|
|
the \fIred\fR, \fIgreen\fR, and \fIblue\fR fields of the structure
|
| 81 |
|
|
pointed to by \fIcolorPtr\fR.
|
| 82 |
|
|
.PP
|
| 83 |
|
|
If \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR is successful
|
| 84 |
|
|
in allocating the desired color, then it returns a pointer to
|
| 85 |
|
|
an XColor structure; the structure indicates the exact intensities of
|
| 86 |
|
|
the allocated color (which may differ slightly from those requested,
|
| 87 |
|
|
depending on the limitations of the screen) and a pixel value
|
| 88 |
|
|
that may be used to draw in the color.
|
| 89 |
|
|
If the colormap for \fItkwin\fR is full, \fBTk_GetColor\fR
|
| 90 |
|
|
and \fBTk_GetColorByValue\fR will use the closest existing color
|
| 91 |
|
|
in the colormap.
|
| 92 |
|
|
If \fBTk_GetColor\fR encounters an error while allocating
|
| 93 |
|
|
the color (such as an unknown color name) then NULL is returned and
|
| 94 |
|
|
an error message is stored in \fIinterp->result\fR;
|
| 95 |
|
|
\fBTk_GetColorByValue\fR never returns an error.
|
| 96 |
|
|
.PP
|
| 97 |
|
|
\fBTk_GetColor\fR and \fBTk_GetColorByValue\fR maintain a database
|
| 98 |
|
|
of all the colors currently in use.
|
| 99 |
|
|
If the same \fInameId\fR is requested multiple times from
|
| 100 |
|
|
\fBTk_GetColor\fR (e.g. by different windows), or if the
|
| 101 |
|
|
same intensities are requested multiple times from
|
| 102 |
|
|
\fBTk_GetColorByValue\fR, then existing pixel values will
|
| 103 |
|
|
be re-used. Re-using an existing pixel avoids any interaction
|
| 104 |
|
|
with the X server, which makes the allocation much more
|
| 105 |
|
|
efficient. For this reason, you should generally use
|
| 106 |
|
|
\fBTk_GetColor\fR or \fBTk_GetColorByValue\fR
|
| 107 |
|
|
instead of Xlib procedures like \fBXAllocColor\fR,
|
| 108 |
|
|
\fBXAllocNamedColor\fR, or \fBXParseColor\fR.
|
| 109 |
|
|
.PP
|
| 110 |
|
|
Since different calls to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR
|
| 111 |
|
|
may return the same shared
|
| 112 |
|
|
pixel value, callers should never change the color of a pixel
|
| 113 |
|
|
returned by the procedures.
|
| 114 |
|
|
If you need to change a color value dynamically, you should use
|
| 115 |
|
|
\fBXAllocColorCells\fR to allocate the pixel value for the color.
|
| 116 |
|
|
.PP
|
| 117 |
|
|
The procedure \fBTk_NameOfColor\fR is roughly the inverse of
|
| 118 |
|
|
\fBTk_GetColor\fR. If its \fIcolorPtr\fR argument was created
|
| 119 |
|
|
by \fBTk_GetColor\fR, then the return value is the \fInameId\fR
|
| 120 |
|
|
string that was passed to \fBTk_GetColor\fR to create the
|
| 121 |
|
|
color. If \fIcolorPtr\fR was created by a call to \fBTk_GetColorByValue\fR,
|
| 122 |
|
|
or by any other mechanism, then the return value is a string
|
| 123 |
|
|
that could be passed to \fBTk_GetColor\fR to return the same
|
| 124 |
|
|
color. Note: the string returned by \fBTk_NameOfColor\fR is
|
| 125 |
|
|
only guaranteed to persist until the next call to \fBTk_NameOfColor\fR.
|
| 126 |
|
|
.PP
|
| 127 |
|
|
\fBTk_GCForColor\fR returns a graphics context whose \fBForeground\fR
|
| 128 |
|
|
field is the pixel allocated for \fIcolorPtr\fR and whose other fields
|
| 129 |
|
|
all have default values.
|
| 130 |
|
|
This provides an easy way to do basic drawing with a color.
|
| 131 |
|
|
The graphics context is cached with the color and will exist only as
|
| 132 |
|
|
long as \fIcolorPtr\fR exists; it is freed when the last reference
|
| 133 |
|
|
to \fIcolorPtr\fR is freed by calling \fBTk_FreeColor\fR.
|
| 134 |
|
|
.PP
|
| 135 |
|
|
When a pixel value returned by \fBTk_GetColor\fR or
|
| 136 |
|
|
\fBTk_GetColorByValue\fR is no longer
|
| 137 |
|
|
needed, \fBTk_FreeColor\fR should be called to release the color.
|
| 138 |
|
|
There should be exactly one call to \fBTk_FreeColor\fR for
|
| 139 |
|
|
each call to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR.
|
| 140 |
|
|
When a pixel value is no longer in
|
| 141 |
|
|
use anywhere (i.e. it has been freed as many times as it has been gotten)
|
| 142 |
|
|
\fBTk_FreeColor\fR will release it to the X server and delete it from
|
| 143 |
|
|
the database.
|
| 144 |
|
|
|
| 145 |
|
|
.SH KEYWORDS
|
| 146 |
|
|
color, intensity, pixel value
|
