HPUX GetGC[3]

 Tk_GetGC(3)                         Tk                          Tk_GetGC(3)

 Tk Library Procedures                                 Tk Library Procedures





 ___________________________________________________________________________

 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



                                    - 1 -        Formatted:  August 11, 1996






 Tk_GetGC(3)                         Tk                          Tk_GetGC(3)

 Tk Library Procedures                                 Tk Library Procedures





      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

































                                    - 2 -        Formatted:  August 11, 1996