TkGetGC(3) Tk Library Procedures TkGetGC(3)

NAME
       TkGetGC, TkFreeGC - maintain database of read-only graphics contexts

SYNOPSIS
       ##iinncclluuddee <>

       GC
       TTkkGGeettGGCC(tkwin, valueMask, valuePtr)

       TTkkFFrreeeeGGCC((display, gc)

AARRGGUUMMEENNTTSS
       TkWindow       tkwin       (in)      Token  for  window  in  which the
                                             graphics context will be used.

       unsigned long   valueMask   (in)      Mask of  bits  (such  as  GGCCFFoorree-
                                             ggrroouunndd  or  GGCCSSttiippppllee) indicating
                                             which  fields  of  *valuePtr  are
                                             valid.

       XGCValues       *valuePtr   (in)      Pointer  to  structure describing
                                             the desired values for the graph-
                                             ics context.

       Display         *display    (in)      Display  for  which  gc was allo-
                                             cated.

       GC              gc          (in)      X identifier for graphics context
                                             that  is  no longer needed.  Must
                                             have been allocated by  TTkkGGeettGGCC.



DESCRIPTION
       TTkkGGeettGGCC  and  TTkkFFrreeeeGGCC 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.   TTkkGGeettGGCC  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.

       TTkkGGeettGGCC maintains a database of all the graphics contexts it has  cre-
       ated.   Whenever  possible,  a call to TTkkGGeettGGCC will return an existing
       graphics context rather than creating a new  one.   This  approach  can
       substantially  reduce  server overhead, so TTkkGGeettGGCC should generally be
       used in preference to the Xlib procedure XXCCrreeaatteeGGCC, which creates a new
       graphics context on each call.

       Since  the  return  values of TTkkGGeettGGCC are shared, callers should never
       modify the graphics contexts returned by TTkkGGeettGGCC.  If a graphics  con-
       text must be modified dynamically, then it should be created by calling
       XXCCrreeaatteeGGCC instead of TTkkGGeettGGCC.

       When a graphics context is no longer needed, TTkkFFrreeeeGGCC should be called
       to  release it.  There should be exactly one call to TTkkFFrreeeeGGCC for each
       call to TTkkGGeettGGCC.  When a graphics context is no longer in use anywhere
       (i.e.  it has been freed as many times as it has been gotten) TTkkFFrreeeeGGCC
       will release it to the X server and delete it from the database.


KKEEYYWWOORRDDSS
       graphics context



Tk                                                                 TkGetGC(3)