Tk_GetGC(3) Tk Library Procedures Tk_GetGC(3)_________________________________________________________________NAME
Tk_GetGC, Tk_FreeGC - maintain database of read-only
graphics contexts
SYNOPSIS
#include <tk.h>
GC
Tk_GetGC(tkwin, valueMask, valuePtr)
Tk_FreeGC(display, gc)
ARGUMENTS
Tk_Window tkwin (in) Token for window in
which the graphics
context will be
used.
unsigned long valueMask (in) Mask of bits (such
as GCForeground or
GCStipple) indicat-
ing which fields of
*valuePtr are valid.
XGCValues *valuePtr (in) Pointer to structure
describing the
desired values for
the graphics con-
text.
Display *display (in) Display for which gc
was allocated.
GC gc (in) X identifier for
graphics context
that is no longer
needed. Must have
been allocated by
Tk_GetGC.
_________________________________________________________________DESCRIPTION
Tk_GetGC and 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. Tk_GetGC takes arguments
describing the desired graphics context and returns an X
identifier for a GC that fits the description. The graph-
ics context that is returned will have default values in
all of the fields not specified explicitly by valueMask
Tk 1
Tk_GetGC(3) Tk Library Procedures Tk_GetGC(3)
and valuePtr.
Tk_GetGC maintains a database of all the graphics contexts
it has created. Whenever possible, a call to Tk_GetGC
will return an existing graphics context rather than cre-
ating a new one. This approach can substantially reduce
server overhead, so Tk_GetGC should generally be used in
preference to the Xlib procedure XCreateGC, which creates
a new graphics context on each call.
Since the return values of Tk_GetGC are shared, callers
should never modify the graphics contexts returned by
Tk_GetGC. If a graphics context must be modified dynami-
cally, then it should be created by calling XCreateGC
instead of Tk_GetGC.
When a graphics context is no longer needed, Tk_FreeGC
should be called to release it. There should be exactly
one call to Tk_FreeGC for each call to 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) Tk_FreeGC
will release it to the X server and delete it from the
database.
KEYWORDS
graphics context
Tk 2