This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).

Tk_GetGC(3)                                 Tk Library Procedures                                Tk_GetGC(3)



____________________________________________________________________________________________________________

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 con-text context
       text that is returned will have default values in all of the fields not specified explicitly by  val-ueMask valueMask
       ueMask 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(3)