# 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.
#
#
=head1 NAME
Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor - maintain database of colors
=for category C Programming
=head1 SYNOPSIS
B<#include E<lt>tk.hE<gt>>
XColor *
B<Tk_GetColor>(I<interp, tkwin, nameId>B<)>
XColor *
B<Tk_GetColorByValue>(I<tkwin, prefPtr>B<)>
char *
B<Tk_NameOfColor(>I<colorPtr>B<)>
GC
B<Tk_GCForColor>(I<colorPtr, drawable>)
B<Tk_FreeColor(>I<colorPtr>B<)>
=head1 ARGUMENTS
=over 4
=item Tcl_Interp *interp (in)
Interpreter to use for error reporting.
=item Tk_Window tkwin (in)
Token for window in which color will be used.
=item Tk_Uid nameId (in)
Textual description of desired color.
=item XColor *prefPtr (in)
Indicates red, green, and blue intensities of desired
color.
=item XColor *colorPtr (in)
Pointer to X color information. Must have been allocated by previous
call to B<Tk_GetColor> or B<Tk_GetColorByValue>, except when passed
to B<Tk_NameOfColor>.
=item 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.
=back
=head1 DESCRIPTION
The B<Tk_GetColor> and B<Tk_GetColorByValue> procedures
locate pixel values that may be used to render particular
colors in the window given by I<tkwin>. In B<Tk_GetColor>
the desired color is specified with a Tk_Uid (I<nameId>), which
may have any of the following forms:
=over 4
=item I<colorname>
Any of the valid textual names for a color defined in the
server's color database file, such as B<red> or B<PeachPuff>.
=item B<#>I<RGB>
=item B<#>I<RRGGBB>
=item B<#>I<RRRGGGBBB>
=item B<#>I<RRRRGGGGBBBB>
A numeric specification of the red, green, and blue intensities
to use to display the color. Each I<R>, I<G>, or I<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 B<Tk_GetColorByValue>, the desired color is indicated with
the I<red>, I<green>, and I<blue> fields of the structure
pointed to by I<colorPtr>.
If B<Tk_GetColor> or B<Tk_GetColorByValue> 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 I<tkwin> is full, B<Tk_GetColor>
and B<Tk_GetColorByValue> will use the closest existing color
in the colormap.
If B<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 I<interp-E<gt>result>;
B<Tk_GetColorByValue> never returns an error.
B<Tk_GetColor> and B<Tk_GetColorByValue> maintain a database
of all the colors currently in use.
If the same I<nameId> is requested multiple times from
B<Tk_GetColor> (e.g. by different windows), or if the
same intensities are requested multiple times from
B<Tk_GetColorByValue>, 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
B<Tk_GetColor> or B<Tk_GetColorByValue>
instead of Xlib procedures like B<XAllocColor>,
B<XAllocNamedColor>, or B<XParseColor>.
Since different calls to B<Tk_GetColor> or B<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
B<XAllocColorCells> to allocate the pixel value for the color.
The procedure B<Tk_NameOfColor> is roughly the inverse of
B<Tk_GetColor>. If its I<colorPtr> argument was created
by B<Tk_GetColor>, then the return value is the I<nameId>
string that was passed to B<Tk_GetColor> to create the
color. If I<colorPtr> was created by a call to B<Tk_GetColorByValue>,
or by any other mechanism, then the return value is a string
that could be passed to B<Tk_GetColor> to return the same
color. Note: the string returned by B<Tk_NameOfColor> is
only guaranteed to persist until the next call to B<Tk_NameOfColor>.
B<Tk_GCForColor> returns a graphics context whose B<Foreground>
field is the pixel allocated for I<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 I<colorPtr> exists; it is freed when the last reference
to I<colorPtr> is freed by calling B<Tk_FreeColor>.
When a pixel value returned by B<Tk_GetColor> or
B<Tk_GetColorByValue> is no longer
needed, B<Tk_FreeColor> should be called to release the color.
There should be exactly one call to B<Tk_FreeColor> for
each call to B<Tk_GetColor> or B<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)
B<Tk_FreeColor> will release it to the X server and delete it from
the database.
=back
=head1 KEYWORDS
color, intensity, pixel value