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 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 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	    | SUNWTk	      |
       +--------------------+-----------------+
       |Interface Stability | Uncommitted     |
       +--------------------+-----------------+
NOTES

       Source for Tk is available on http://opensolaris.org.

Tk																     Tk_GetGC(3TK)