Scroll to navigation

Tk_GetGC(3tk) Tk Library Procedures Tk_GetGC(3tk) 





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 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