#  Copyright (c) 1990 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_GetGC, Tk_FreeGC - maintain database of read-only graphics contexts

=for category C Programming

=head1 SYNOPSIS

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

GC
B<Tk_GetGC>(I<tkwin, valueMask, valuePtr>)

B<Tk_FreeGC(>I<display, gc>)

=head1 ARGUMENTS

=over 4

=item Tk_Window tkwin (in)

Token for window in which the graphics context will be used.

=item "unsigned long" valueMask (in)

Mask of bits (such as B<GCForeground> or B<GCStipple>)
indicating which fields of I<*valuePtr> are valid.

=item XGCValues *valuePtr (in)

Pointer to structure describing the desired values for the
graphics context.

=item Display *display (in)

Display for which I<gc> was allocated.

=item GC gc (in)

X identifier for graphics context that is no longer needed.
Must have been allocated by B<Tk_GetGC>.

=back

=head1 DESCRIPTION

B<Tk_GetGC> and B<Tk_FreeGC> manage a collection of graphics contexts
being used by an application.  The procedures allow graphics contexts to be
shared, thereby avoiding the server overhead that would be incurred
if a separate GC were created for each use.  B<Tk_GetGC> takes arguments
describing the desired graphics context and returns an X identifier
for a GC that fits the description.  The graphics context that is returned
will have default values in all of the fields not specified explicitly
by I<valueMask> and I<valuePtr>.

B<Tk_GetGC> maintains a
database of all the graphics contexts it has created.  Whenever possible,
a call to B<Tk_GetGC> will
return an existing graphics context rather than creating a new one.  This
approach can substantially reduce server overhead, so B<Tk_GetGC>
should generally be used in preference to the Xlib procedure
B<XCreateGC>, which creates a new graphics context on each call.

Since the return values of B<Tk_GetGC>
are shared, callers should never modify the graphics contexts
returned by B<Tk_GetGC>.
If a graphics context must be modified dynamically, then it should be
created by calling B<XCreateGC> instead of B<Tk_GetGC>.

When a graphics context
is no longer needed, B<Tk_FreeGC> should be called to release it.
There should be exactly one call to B<Tk_FreeGC> for
each call to B<Tk_GetGC>.
When a graphics context is no longer in use anywhere (i.e. it has
been freed as many times as it has been gotten) B<Tk_FreeGC>
will release it to the X server and delete it from the database.

=head1 KEYWORDS

graphics context