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 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 Tk_GetGC(3)