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