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
39

DESCRIPTION

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

KEYWORDS

70       graphics context
71
72
73
74Tk                                                                 Tk_GetGC(3)