Tk_GetGC(3)

Tk_GetGC(3)           Tk Library Procedures           Tk_GetGC(3)

_________________________________________________________________

NAME

     Tk_GetGC, Tk_FreeGC - maintain database of read-only  graph-
     ics 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  graph-
                                           ics 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 allo-
                                           cated by Tk_GetGC.
_________________________________________________________________

DESCRIPTION

     Tk_GetGC and Tk_FreeGC manage a collection of graphics  con-
     texts  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                        Last change:                          1

Tk_GetGC(3)           Tk Library Procedures           Tk_GetGC(3)

     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 graph-
     ics 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  graph-
     ics  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                        Last change:                          2