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