Tk_GetGC(3Tk)							 Tk_GetGC(3Tk)

NAME    [Toc]    [Back]

     Tk_GetGC, Tk_FreeGC - maintain database of	read-only graphics contexts

SYNOPSIS    [Toc]    [Back]

     #include <tk.h>

     GC
     Tk_GetGC(tkwin, valueMask,	valuePtr)

     Tk_FreeGC(display,	gc)

ARGUMENTS    [Toc]    [Back]

     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    [Toc]    [Back]

     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.




									Page 1






Tk_GetGC(3Tk)							 Tk_GetGC(3Tk)



     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    [Toc]    [Back]

     graphics context


									PPPPaaaaggggeeee 2222