#  Copyright (c) 1994 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_GetColormap, Tk_FreeColormap - allocate and free colormaps

=for category C Programming

=head1 SYNOPSIS

B<#include E<lt>tk.hE<gt>>

Colormap
B<Tk_GetColormap(>I<interp, tkwin, string>B<)>

B<Tk_FreeColormap(>I<display, colormap>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 colormap will be used.

=item char *string (in)

Selects a colormap:  either B<new> or the name of a window
with the same screen and visual as I<tkwin>.

=item Display *display (in)

Display for which I<colormap> was allocated.

=item Colormap colormap (in)

Colormap to free;  must have been returned by a previous
call to B<Tk_GetColormap> or B<Tk_GetVisual>.

=back

=head1 DESCRIPTION

These procedures are used to manage colormaps.
B<Tk_GetColormap> returns a colormap suitable for use in I<tkwin>.
If its I<string> argument is B<new> then a new colormap is
created;  otherwise I<string> must be the name of another window
with the same screen and visual as I<tkwin>, and the colormap from that
window is returned.
If I<string> doesn't make sense, or if it refers to a window on
a different screen from I<tkwin> or with
a different visual than I<tkwin>, then B<Tk_GetColormap> returns
B<None> and leaves an error message in I<interp-E<gt>result>.

B<Tk_FreeColormap> should be called when a colormap returned by
B<Tk_GetColormap> is no longer needed.
Tk maintains a reference count for each colormap returned by
B<Tk_GetColormap>, so there should eventually be one call to
B<Tk_FreeColormap> for each call to B<Tk_GetColormap>.
When a colormap's reference count becomes zero, Tk releases the
X colormap.

B<Tk_GetVisual> and B<Tk_GetColormap> work together, in that
a new colormap created by B<Tk_GetVisual> may later be returned
by B<Tk_GetColormap>.
The reference counting mechanism for colormaps includes both procedures,
so callers of B<Tk_GetVisual> must also call B<Tk_FreeColormap>
to release the colormap.
If B<Tk_GetColormap> is called with a I<string> value of
B<new> then the resulting colormap will never
be returned by B<Tk_GetVisual>;  however, it can be used in other
windows by calling B<Tk_GetColormap> with the original window's
name as I<string>.

=head1 KEYWORDS

colormap