archie/tk4.2/doc/GetColor.3

147 lines
5.7 KiB
Groff
Raw Permalink Normal View History

2024-05-27 16:13:40 +02:00
'\"
'\" Copyright (c) 1990, 1991 The Regents of the University of California.
2024-05-27 16:40:40 +02:00
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
2024-05-27 16:13:40 +02:00
'\"
2024-05-27 16:40:40 +02:00
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
2024-05-27 16:13:40 +02:00
'\"
2024-05-27 16:40:40 +02:00
'\" SCCS: @(#) GetColor.3 1.22 96/08/27 13:21:26
2024-05-27 16:13:40 +02:00
'\"
.so man.macros
2024-05-27 16:40:40 +02:00
.TH Tk_GetColor 3 4.0 Tk "Tk Library Procedures"
2024-05-27 16:13:40 +02:00
.BS
.SH NAME
2024-05-27 16:40:40 +02:00
Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor \- maintain database of colors
2024-05-27 16:13:40 +02:00
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
XColor *
2024-05-27 16:40:40 +02:00
\fBTk_GetColor\fR(\fIinterp, tkwin, nameId\fB)\fR
2024-05-27 16:13:40 +02:00
.sp
XColor *
2024-05-27 16:40:40 +02:00
\fBTk_GetColorByValue\fR(\fItkwin, prefPtr\fB)\fR
2024-05-27 16:13:40 +02:00
.sp
char *
\fBTk_NameOfColor(\fIcolorPtr\fB)\fR
.sp
2024-05-27 16:40:40 +02:00
GC
\fBTk_GCForColor\fR(\fIcolorPtr, drawable\fR)
.sp
2024-05-27 16:13:40 +02:00
\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.
2024-05-27 16:40:40 +02:00
.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.
2024-05-27 16:13:40 +02:00
.BE
.SH DESCRIPTION
.PP
The \fBTk_GetColor\fR and \fBTk_GetColorByValue\fR procedures
locate pixel values that may be used to render particular
2024-05-27 16:40:40 +02:00
colors in the window given by \fItkwin\fR. In \fBTk_GetColor\fR
2024-05-27 16:13:40 +02:00
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.
2024-05-27 16:40:40 +02:00
.PP
2024-05-27 16:13:40 +02:00
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
2024-05-27 16:40:40 +02:00
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.
2024-05-27 16:13:40 +02:00
.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
2024-05-27 16:40:40 +02:00
\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
2024-05-27 16:13:40 +02:00
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