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

       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