1Tk_GetGC(3)                  Tk Library Procedures                 Tk_GetGC(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

11       #include <tk.h>
12
13       GC
14       Tk_GetGC(tkwin, valueMask, valuePtr)
15
16       Tk_FreeGC(display, gc)
17

ARGUMENTS

19       Tk_Window tkwin (in)                  Token  for  window  in  which the
20                                             graphics context will be used.
21
22       unsigned long valueMask (in)          Mask of  bits  (such  as  GCFore‐
23                                             ground  or  GCStipple) indicating
24                                             which  fields  of  *valuePtr  are
25                                             valid.
26
27       XGCValues *valuePtr (in)              Pointer  to  structure describing
28                                             the desired values for the graph‐
29                                             ics context.
30
31       Display *display (in)                 Display  for  which  gc was allo‐
32                                             cated.
33
34       GC gc (in)                            X identifier for graphics context
35                                             that  is  no longer needed.  Must
36                                             have been allocated by Tk_GetGC.
37______________________________________________________________________________
38

DESCRIPTION

40       Tk_GetGC and Tk_FreeGC manage a collection of graphics  contexts  being
41       used  by  an application.  The procedures allow graphics contexts to be
42       shared, thereby avoiding the server overhead that would be incurred  if
43       a  separate GC were created for each use.  Tk_GetGC takes arguments de‐
44       scribing the desired graphics context and returns an X identifier for a
45       GC  that  fits  the description.  The graphics context that is returned
46       will have default values in all of the fields not specified  explicitly
47       by valueMask and valuePtr.
48
49       Tk_GetGC  maintains a database of all the graphics contexts it has cre‐
50       ated.  Whenever possible, a call to Tk_GetGC will  return  an  existing
51       graphics  context  rather  than  creating a new one.  This approach can
52       substantially reduce server overhead, so Tk_GetGC should  generally  be
53       used in preference to the Xlib procedure XCreateGC, which creates a new
54       graphics context on each call.
55
56       Since the return values of Tk_GetGC are shared,  callers  should  never
57       modify  the graphics contexts returned by Tk_GetGC.  If a graphics con‐
58       text must be modified dynamically, then it should be created by calling
59       XCreateGC instead of Tk_GetGC.
60
61       When a graphics context is no longer needed, Tk_FreeGC should be called
62       to release it.  There should be exactly one call to Tk_FreeGC for  each
63       call to Tk_GetGC.  When a graphics context is no longer in use anywhere
64       (i.e. it has been freed as many times as it has been gotten)  Tk_FreeGC
65       will release it to the X server and delete it from the database.
66

KEYWORDS

68       graphics context
69
70
71
72Tk                                                                 Tk_GetGC(3)