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

Tk                                                                                                 Tk_GetGC(3tk)