Manual Pages for UNIX Operating System command usage for man Tk_GetGC

Tk Library Procedures                               Tk_GetGC(3TK)



_________________________________________________________________

NAME
     Tk_GetGC, Tk_FreeGC - maintain database of read-only  graph-
     ics contexts

SYNOPSIS
     #include 

     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 Library Procedures                               Tk_GetGC(3TK)



     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

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tk-8   |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tk is available on http://opensolaris.org.
















Tk                        Last change:                          2