2 '\" Copyright (c) 1990 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 '\" RCS: @(#) $Id: GetGC.3,v 1.2 1998/09/14 18:22:49 stanton Exp $
10 '\" The definitions below are for supplemental macros used in Tcl/Tk
13 '\" .AP type name in/out ?indent?
14 '\" Start paragraph describing an argument to a library procedure.
15 '\" type is type of argument (int, etc.), in/out is either "in", "out",
16 '\" or "in/out" to describe whether procedure reads or modifies arg,
17 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
18 '\" needed; use .AS below instead)
21 '\" Give maximum sizes of arguments for setting tab stops. Type and
22 '\" name are examples of largest possible arguments that will be passed
23 '\" to .AP later. If args are omitted, default tab stops are used.
26 '\" Start box enclosure. From here until next .BE, everything will be
27 '\" enclosed in one large box.
30 '\" End of box enclosure.
33 '\" Begin code excerpt.
38 '\" .VS ?version? ?br?
39 '\" Begin vertical sidebar, for use in marking newly-changed parts
40 '\" of man pages. The first argument is ignored and used for recording
41 '\" the version when the .VS was added, so that the sidebars can be
42 '\" found and removed when they reach a certain age. If another argument
43 '\" is present, then a line break is forced before starting the sidebar.
46 '\" End of vertical sidebar.
49 '\" Begin an indented unfilled display.
52 '\" End of indented unfilled display.
55 '\" Start of list of standard options for a Tk widget. The
56 '\" options follow on successive lines, in four columns separated
60 '\" End of list of standard options for a Tk widget.
62 '\" .OP cmdName dbName dbClass
63 '\" Start of description of a specific option. cmdName gives the
64 '\" option's name as specified in the class command, dbName gives
65 '\" the option's name in the option database, and dbClass gives
66 '\" the option's class in the option database.
69 '\" Print arg1 underlined, then print arg2 normally.
71 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
73 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
77 '\" # Start an argument description
81 . ie !"\\$2"" .TP \\n()Cu
86 \&\\$1 \\fI\\$2\\fP (\\$3)
99 '\" # define tabbing values for .AP
102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
108 .AS Tcl_Interp Tcl_CreateInterp in/out
109 '\" # BS - start boxed text
110 '\" # ^y = starting y location
118 .if n \l'\\n(.lu\(ul'
121 '\" # BE - end boxed text (draw box now)
126 .ie n \l'\\n(^lu\(ul'
128 .\" Draw four-sided box normally, but don't draw top of
129 .\" box if the box started on an earlier page.
131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
141 '\" # VS - start vertical sidebar
142 '\" # ^Y = starting y location
143 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
147 .ie n 'mc \s12\(br\s0
150 '\" # VE - end of vertical sidebar
158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
165 '\" # Special macro to handle page bottom: finish off current
166 '\" # box/sidebar if in box/sidebar mode, then invoked standard
167 '\" # page bottom macro.
174 .\" Draw three-sided box if this is the box's first page,
175 .\" draw two sides but no top otherwise.
176 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
180 .nr ^x \\n(^tu+1v-\\n(^Yu
181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
194 '\" # DS - begin display
200 '\" # DE - end display
206 '\" # SO - start of list of standard options
208 .SH "STANDARD OPTIONS"
214 '\" # SE - end of list of standard options
219 See the \\fBoptions\\fR manual entry for details on the standard options.
221 '\" # OP - start of full description for a single option
226 Command-Line Name: \\fB\\$1\\fR
227 Database Name: \\fB\\$2\\fR
228 Database Class: \\fB\\$3\\fR
232 '\" # CS - begin code excerpt
238 '\" # CE - end code excerpt
246 .TH Tk_GetGC 3 "" Tk "Tk Library Procedures"
249 Tk_GetGC, Tk_FreeGC \- maintain database of read-only graphics contexts
252 \fB#include <tk.h>\fR
255 \fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR)
257 \fBTk_FreeGC(\fIdisplay, gc\fR)
259 .AS "unsigned long" valueMask
260 .AP Tk_Window tkwin in
261 Token for window in which the graphics context will be used.
262 .AP "unsigned long" valueMask in
263 Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR)
264 indicating which fields of \fI*valuePtr\fR are valid.
265 .AP XGCValues *valuePtr in
266 Pointer to structure describing the desired values for the
268 .AP Display *display in
269 Display for which \fIgc\fR was allocated.
271 X identifier for graphics context that is no longer needed.
272 Must have been allocated by \fBTk_GetGC\fR.
277 \fBTk_GetGC\fR and \fBTk_FreeGC\fR manage a collection of graphics contexts
278 being used by an application. The procedures allow graphics contexts to be
279 shared, thereby avoiding the server overhead that would be incurred
280 if a separate GC were created for each use. \fBTk_GetGC\fR takes arguments
281 describing the desired graphics context and returns an X identifier
282 for a GC that fits the description. The graphics context that is returned
283 will have default values in all of the fields not specified explicitly
284 by \fIvalueMask\fR and \fIvaluePtr\fR.
286 \fBTk_GetGC\fR maintains a
287 database of all the graphics contexts it has created. Whenever possible,
288 a call to \fBTk_GetGC\fR will
289 return an existing graphics context rather than creating a new one. This
290 approach can substantially reduce server overhead, so \fBTk_GetGC\fR
291 should generally be used in preference to the Xlib procedure
292 \fBXCreateGC\fR, which creates a new graphics context on each call.
294 Since the return values of \fBTk_GetGC\fR
295 are shared, callers should never modify the graphics contexts
296 returned by \fBTk_GetGC\fR.
297 If a graphics context must be modified dynamically, then it should be
298 created by calling \fBXCreateGC\fR instead of \fBTk_GetGC\fR.
300 When a graphics context
301 is no longer needed, \fBTk_FreeGC\fR should be called to release it.
302 There should be exactly one call to \fBTk_FreeGC\fR for
303 each call to \fBTk_GetGC\fR.
304 When a graphics context is no longer in use anywhere (i.e. it has
305 been freed as many times as it has been gotten) \fBTk_FreeGC\fR
306 will release it to the X server and delete it from the database.