Tk_GetGC(3TK) Tk Library Procedures Tk_GetGC(3TK)______________________________________________________________________________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 GCFore‐
ground or GCStipple) indicating
which fields of *valuePtr are
valid.
XGCValues *valuePtr (in) Pointer to structure describing
the desired values for the graph‐
ics context.
Display *display (in) Display for which gc was allo‐
cated.
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 cre‐
ated. 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 con‐
text 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
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌────────────────────┬─────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────┤
│Availability │ runtime/tk-8 │
├────────────────────┼─────────────────┤
│Interface Stability │ Uncommitted │
└────────────────────┴─────────────────┘
NOTES
Source for Tk is available on http://opensolaris.org.
TkTk_GetGC(3TK)