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)
indicating which fields of
*valuePtr are valid.

XGCValues *valuePtr (in) Pointer to structure describing
the desired values for the
graphics context.

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 graphics context that is
returned will have default values in all of the fields not specified
explicitly by valueMask 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 creating 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 dynamically, 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 Tk_GetGC(3)