Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1990-1994 The Regents of the University of California. | |
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
4 | '\" | |
5 | '\" See the file "license.terms" for information on usage and redistribution | |
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
7 | '\" | |
8 | '\" RCS: @(#) $Id: ConfigWidg.3,v 1.8.2.1 2003/10/06 22:15:17 dgp Exp $ | |
9 | '\" | |
10 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
11 | '\" manual entries. | |
12 | '\" | |
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) | |
19 | '\" | |
20 | '\" .AS ?type? ?name? | |
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. | |
24 | '\" | |
25 | '\" .BS | |
26 | '\" Start box enclosure. From here until next .BE, everything will be | |
27 | '\" enclosed in one large box. | |
28 | '\" | |
29 | '\" .BE | |
30 | '\" End of box enclosure. | |
31 | '\" | |
32 | '\" .CS | |
33 | '\" Begin code excerpt. | |
34 | '\" | |
35 | '\" .CE | |
36 | '\" End code excerpt. | |
37 | '\" | |
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. | |
44 | '\" | |
45 | '\" .VE | |
46 | '\" End of vertical sidebar. | |
47 | '\" | |
48 | '\" .DS | |
49 | '\" Begin an indented unfilled display. | |
50 | '\" | |
51 | '\" .DE | |
52 | '\" End of indented unfilled display. | |
53 | '\" | |
54 | '\" .SO | |
55 | '\" Start of list of standard options for a Tk widget. The | |
56 | '\" options follow on successive lines, in four columns separated | |
57 | '\" by tabs. | |
58 | '\" | |
59 | '\" .SE | |
60 | '\" End of list of standard options for a Tk widget. | |
61 | '\" | |
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. | |
67 | '\" | |
68 | '\" .UL arg1 arg2 | |
69 | '\" Print arg1 underlined, then print arg2 normally. | |
70 | '\" | |
71 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
72 | '\" | |
73 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
74 | .if t .wh -1.3i ^B | |
75 | .nr ^l \n(.l | |
76 | .ad b | |
77 | '\" # Start an argument description | |
78 | .de AP | |
79 | .ie !"\\$4"" .TP \\$4 | |
80 | .el \{\ | |
81 | . ie !"\\$2"" .TP \\n()Cu | |
82 | . el .TP 15 | |
83 | .\} | |
84 | .ta \\n()Au \\n()Bu | |
85 | .ie !"\\$3"" \{\ | |
86 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
87 | .\".b | |
88 | .\} | |
89 | .el \{\ | |
90 | .br | |
91 | .ie !"\\$2"" \{\ | |
92 | \&\\$1 \\fI\\$2\\fP | |
93 | .\} | |
94 | .el \{\ | |
95 | \&\\fI\\$1\\fP | |
96 | .\} | |
97 | .\} | |
98 | .. | |
99 | '\" # define tabbing values for .AP | |
100 | .de AS | |
101 | .nr )A 10n | |
102 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
103 | .nr )B \\n()Au+15n | |
104 | .\" | |
105 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
106 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
107 | .. | |
108 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
109 | '\" # BS - start boxed text | |
110 | '\" # ^y = starting y location | |
111 | '\" # ^b = 1 | |
112 | .de BS | |
113 | .br | |
114 | .mk ^y | |
115 | .nr ^b 1u | |
116 | .if n .nf | |
117 | .if n .ti 0 | |
118 | .if n \l'\\n(.lu\(ul' | |
119 | .if n .fi | |
120 | .. | |
121 | '\" # BE - end boxed text (draw box now) | |
122 | .de BE | |
123 | .nf | |
124 | .ti 0 | |
125 | .mk ^t | |
126 | .ie n \l'\\n(^lu\(ul' | |
127 | .el \{\ | |
128 | .\" Draw four-sided box normally, but don't draw top of | |
129 | .\" box if the box started on an earlier page. | |
130 | .ie !\\n(^b-1 \{\ | |
131 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
132 | .\} | |
133 | .el \}\ | |
134 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
135 | .\} | |
136 | .\} | |
137 | .fi | |
138 | .br | |
139 | .nr ^b 0 | |
140 | .. | |
141 | '\" # VS - start vertical sidebar | |
142 | '\" # ^Y = starting y location | |
143 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
144 | .de VS | |
145 | .if !"\\$2"" .br | |
146 | .mk ^Y | |
147 | .ie n 'mc \s12\(br\s0 | |
148 | .el .nr ^v 1u | |
149 | .. | |
150 | '\" # VE - end of vertical sidebar | |
151 | .de VE | |
152 | .ie n 'mc | |
153 | .el \{\ | |
154 | .ev 2 | |
155 | .nf | |
156 | .ti 0 | |
157 | .mk ^t | |
158 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
159 | .sp -1 | |
160 | .fi | |
161 | .ev | |
162 | .\} | |
163 | .nr ^v 0 | |
164 | .. | |
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. | |
168 | .de ^B | |
169 | .ev 2 | |
170 | 'ti 0 | |
171 | 'nf | |
172 | .mk ^t | |
173 | .if \\n(^b \{\ | |
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 | |
178 | .\} | |
179 | .if \\n(^v \{\ | |
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 | |
182 | .\} | |
183 | .bp | |
184 | 'fi | |
185 | .ev | |
186 | .if \\n(^b \{\ | |
187 | .mk ^y | |
188 | .nr ^b 2 | |
189 | .\} | |
190 | .if \\n(^v \{\ | |
191 | .mk ^Y | |
192 | .\} | |
193 | .. | |
194 | '\" # DS - begin display | |
195 | .de DS | |
196 | .RS | |
197 | .nf | |
198 | .sp | |
199 | .. | |
200 | '\" # DE - end display | |
201 | .de DE | |
202 | .fi | |
203 | .RE | |
204 | .sp | |
205 | .. | |
206 | '\" # SO - start of list of standard options | |
207 | .de SO | |
208 | .SH "STANDARD OPTIONS" | |
209 | .LP | |
210 | .nf | |
211 | .ta 5.5c 11c | |
212 | .ft B | |
213 | .. | |
214 | '\" # SE - end of list of standard options | |
215 | .de SE | |
216 | .fi | |
217 | .ft R | |
218 | .LP | |
219 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
220 | .. | |
221 | '\" # OP - start of full description for a single option | |
222 | .de OP | |
223 | .LP | |
224 | .nf | |
225 | .ta 4c | |
226 | Command-Line Name: \\fB\\$1\\fR | |
227 | Database Name: \\fB\\$2\\fR | |
228 | Database Class: \\fB\\$3\\fR | |
229 | .fi | |
230 | .IP | |
231 | .. | |
232 | '\" # CS - begin code excerpt | |
233 | .de CS | |
234 | .RS | |
235 | .nf | |
236 | .ta .25i .5i .75i 1i | |
237 | .. | |
238 | '\" # CE - end code excerpt | |
239 | .de CE | |
240 | .fi | |
241 | .RE | |
242 | .. | |
243 | .de UL | |
244 | \\$1\l'|0\(ul'\\$2 | |
245 | .. | |
246 | .TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures" | |
247 | .BS | |
248 | .SH NAME | |
249 | Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets | |
250 | .SH SYNOPSIS | |
251 | .nf | |
252 | \fB#include <tk.h>\fR | |
253 | .sp | |
254 | int | |
255 | \fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR | |
256 | .sp | |
257 | int | |
258 | \fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR | |
259 | .sp | |
260 | int | |
261 | \fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR | |
262 | .sp | |
263 | \fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR | |
264 | .SH ARGUMENTS | |
265 | .AS Tk_ConfigSpec *widgRec in/out | |
266 | .AP Tcl_Interp *interp in | |
267 | Interpreter to use for returning error messages. | |
268 | .AP Tk_Window tkwin in | |
269 | Window used to represent widget (needed to set up X resources). | |
270 | .AP Tk_ConfigSpec *specs in | |
271 | Pointer to table specifying legal configuration options for this | |
272 | widget. | |
273 | .AP int argc in | |
274 | Number of arguments in \fIargv\fR. | |
275 | .AP "CONST char" **argv in | |
276 | Command-line options for configuring widget. | |
277 | .AP char *widgRec in/out | |
278 | Points to widget record structure. Fields in this structure get | |
279 | modified by \fBTk_ConfigureWidget\fR to hold configuration information. | |
280 | .AP int flags in | |
281 | If non-zero, then it specifies an OR-ed combination of flags that | |
282 | control the processing of configuration information. | |
283 | TK_CONFIG_ARGV_ONLY causes the option database and defaults to be | |
284 | ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to | |
285 | selectively disable entries in \fIspecs\fR. | |
286 | .AP "type name" type in | |
287 | The name of the type of a widget record. | |
288 | .AP "field name" field in | |
289 | The name of a field in records of type \fItype\fR. | |
290 | .AP "CONST char" *argvName in | |
291 | The name used on Tcl command lines to refer to a particular option | |
292 | (e.g. when creating a widget or invoking the \fBconfigure\fR widget | |
293 | command). If non-NULL, then information is returned only for this | |
294 | option. If NULL, then information is returned for all available | |
295 | options. | |
296 | .AP Display *display in | |
297 | Display containing widget whose record is being freed; needed in | |
298 | order to free up resources. | |
299 | .BE | |
300 | .SH DESCRIPTION | |
301 | .VS 8.1 | |
302 | .PP | |
303 | Note: \fBTk_ConfigureWidget\fP should be replaced with the new | |
304 | \fBTcl_Obj\fP based API \fBTk_SetOptions\fP. The old interface is | |
305 | retained for backward compatibility. | |
306 | .VE | |
307 | .PP | |
308 | \fBTk_ConfigureWidget\fR is called to configure various aspects of a | |
309 | widget, such as colors, fonts, border width, etc. | |
310 | It is intended as a convenience procedure to reduce the amount | |
311 | of code that must be written in individual widget managers to | |
312 | handle configuration information. | |
313 | It is typically | |
314 | invoked when widgets are created, and again when the \fBconfigure\fR | |
315 | command is invoked for a widget. | |
316 | Although intended primarily for widgets, \fBTk_ConfigureWidget\fR | |
317 | can be used in other situations where \fIargc-argv\fR information | |
318 | is to be used to fill in a record structure, such as configuring | |
319 | graphical elements for a canvas widget or entries of a menu. | |
320 | .PP | |
321 | \fBTk_ConfigureWidget\fR processes | |
322 | a table specifying the configuration options that are supported | |
323 | (\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and | |
324 | \fIargv\fR) to fill in fields of a record (\fIwidgRec\fR). | |
325 | It uses the option database and defaults specified in \fIspecs\fR | |
326 | to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR. | |
327 | \fBTk_ConfigureWidget\fR normally returns the value TCL_OK; in this | |
328 | case it does not modify \fIinterp\fR. | |
329 | If an error | |
330 | occurs then TCL_ERROR is returned and \fBTk_ConfigureWidget\fR will | |
331 | leave an error message in \fIinterp->result\fR in the standard Tcl | |
332 | fashion. | |
333 | In the event of an error return, some of the fields of \fIwidgRec\fR | |
334 | could already have been set, if configuration information for them | |
335 | was successfully processed before the error occurred. | |
336 | The other fields will be set to reasonable initial values so that | |
337 | \fBTk_FreeOptions\fR can be called for cleanup. | |
338 | .PP | |
339 | The \fIspecs\fR array specifies the kinds of configuration options | |
340 | expected by the widget. Each of its entries specifies one configuration | |
341 | option and has the following structure: | |
342 | .CS | |
343 | typedef struct { | |
344 | int \fItype\fR; | |
345 | char *\fIargvName\fR; | |
346 | char *\fIdbName\fR; | |
347 | char *\fIdbClass\fR; | |
348 | char *\fIdefValue\fR; | |
349 | int \fIoffset\fR; | |
350 | int \fIspecFlags\fR; | |
351 | Tk_CustomOption *\fIcustomPtr\fR; | |
352 | } Tk_ConfigSpec; | |
353 | .CE | |
354 | The \fItype\fR field indicates what type of configuration option this is | |
355 | (e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for | |
356 | an integer value). The \fItype\fR field indicates how to use the | |
357 | value of the option (more on this below). | |
358 | The \fIargvName\fR field is a string such as ``\-font'' or ``\-bg'', | |
359 | which is compared with the values in \fIargv\fR (if \fIargvName\fR is | |
360 | NULL it means this is a grouped entry; see GROUPED ENTRIES below). The | |
361 | \fIdbName\fR and \fIdbClass\fR fields are used to look up a value | |
362 | for this option in the option database. The \fIdefValue\fR field | |
363 | specifies a default value for this configuration option if no | |
364 | value is specified in either \fIargv\fR or the option database. | |
365 | \fIOffset\fR indicates where in \fIwidgRec\fR to store information | |
366 | about this option, and \fIspecFlags\fR contains additional information | |
367 | to control the processing of this configuration option (see FLAGS | |
368 | below). | |
369 | The last field, \fIcustomPtr\fR, is only used if \fItype\fR is | |
370 | TK_CONFIG_CUSTOM; see CUSTOM OPTION TYPES below. | |
371 | .PP | |
372 | \fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which | |
373 | (if any) configuration options are specified there. \fIArgv\fR | |
374 | must contain an even number of fields; the first of each pair | |
375 | of fields must match the \fIargvName\fR of some entry in \fIspecs\fR | |
376 | (unique abbreviations are acceptable), | |
377 | and the second field of the pair contains the value for that | |
378 | configuration option. If there are entries in \fIspec\fR for which | |
379 | there were no matching entries in \fIargv\fR, | |
380 | \fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR | |
381 | fields of the \fIspecs\fR entry to probe the option database; if | |
382 | a value is found, then it is used as the value for the option. | |
383 | Finally, if no entry is found in the option database, the | |
384 | \fIdefValue\fR field of the \fIspecs\fR entry is used as the | |
385 | value for the configuration option. If the \fIdefValue\fR is | |
386 | NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in | |
387 | \fIflags\fR, then there is no default value and this \fIspecs\fR entry | |
388 | will be ignored if no value is specified in \fIargv\fR or the | |
389 | option database. | |
390 | .PP | |
391 | Once a string value has been determined for a configuration option, | |
392 | \fBTk_ConfigureWidget\fR translates the string value into a more useful | |
393 | form, such as a color if \fItype\fR is TK_CONFIG_COLOR or an integer | |
394 | if \fItype\fR is TK_CONFIG_INT. This value is then stored in the | |
395 | record pointed to by \fIwidgRec\fR. This record is assumed to | |
396 | contain information relevant to the manager of the widget; its exact | |
397 | type is unknown to \fBTk_ConfigureWidget\fR. The \fIoffset\fR field | |
398 | of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store | |
399 | the information about this configuration option. You should use the | |
400 | \fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for | |
401 | a description of \fBTk_Offset\fR). The location indicated by | |
402 | \fIwidgRec\fR and \fIoffset\fR will be referred to as the ``target'' | |
403 | in the descriptions below. | |
404 | .PP | |
405 | The \fItype\fR field of each entry in \fIspecs\fR determines what | |
406 | to do with the string value of that configuration option. The | |
407 | legal values for \fItype\fR, and the corresponding actions, are: | |
408 | .TP | |
409 | \fBTK_CONFIG_ACTIVE_CURSOR\fR | |
410 | The value | |
411 | must be an ASCII string identifying a cursor in a form | |
412 | suitable for passing to \fBTk_GetCursor\fR. | |
413 | The value is converted to a \fBTk_Cursor\fR by calling | |
414 | \fBTk_GetCursor\fR and the result is stored in the target. | |
415 | In addition, the resulting cursor is made the active cursor | |
416 | for \fItkwin\fR by calling \fBXDefineCursor\fR. | |
417 | If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value | |
418 | may be an empty string, in which case the target and \fItkwin\fR's | |
419 | active cursor will be set to \fBNone\fR. | |
420 | If the previous value of the target | |
421 | wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR. | |
422 | .TP | |
423 | \fBTK_CONFIG_ANCHOR\fR | |
424 | The value must be an ASCII string identifying an anchor point in one of the ways | |
425 | accepted by \fBTk_GetAnchor\fR. | |
426 | The string is converted to a \fBTk_Anchor\fR by calling | |
427 | \fBTk_GetAnchor\fR and the result is stored in the target. | |
428 | .TP | |
429 | \fBTK_CONFIG_BITMAP\fR | |
430 | The value must be an ASCII string identifying a bitmap in a form | |
431 | suitable for passing to \fBTk_GetBitmap\fR. The value is converted | |
432 | to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result | |
433 | is stored in the target. | |
434 | If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value | |
435 | may be an empty string, in which case the target is set to \fBNone\fR. | |
436 | If the previous value of the target | |
437 | wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR. | |
438 | .TP | |
439 | \fBTK_CONFIG_BOOLEAN\fR | |
440 | The value must be an ASCII string specifying a boolean value. Any | |
441 | of the values ``true'', ``yes'', ``on'', or ``1'', | |
442 | or an abbreviation of one of these values, means true; | |
443 | any of the values ``false'', ``no'', ``off'', or ``0'', or an abbreviation of | |
444 | one of these values, means false. | |
445 | The target is expected to be an integer; for true values it will | |
446 | be set to 1 and for false values it will be set to 0. | |
447 | .TP | |
448 | \fBTK_CONFIG_BORDER\fR | |
449 | The value must be an ASCII string identifying a border color in a form | |
450 | suitable for passing to \fBTk_Get3DBorder\fR. The value is converted | |
451 | to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result | |
452 | is stored in the target. | |
453 | If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value | |
454 | may be an empty string, in which case the target will be set to NULL. | |
455 | If the previous value of the target | |
456 | wasn't NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR. | |
457 | .TP | |
458 | \fBTK_CONFIG_CAP_STYLE\fR | |
459 | The value must be | |
460 | an ASCII string identifying a cap style in one of the ways | |
461 | accepted by \fBTk_GetCapStyle\fR. | |
462 | The string is converted to an integer value corresponding | |
463 | to the cap style by calling | |
464 | \fBTk_GetCapStyle\fR and the result is stored in the target. | |
465 | .TP | |
466 | \fBTK_CONFIG_COLOR\fR | |
467 | The value must be an ASCII string identifying a color in a form | |
468 | suitable for passing to \fBTk_GetColor\fR. The value is converted | |
469 | to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result | |
470 | is stored in the target. | |
471 | If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value | |
472 | may be an empty string, in which case the target will be set to \fBNone\fR. | |
473 | If the previous value of the target | |
474 | wasn't NULL, then it is freed by passing it to \fBTk_FreeColor\fR. | |
475 | .TP | |
476 | \fBTK_CONFIG_CURSOR\fR | |
477 | This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except | |
478 | that the new cursor is not made the active one for \fItkwin\fR. | |
479 | .TP | |
480 | \fBTK_CONFIG_CUSTOM\fR | |
481 | This option allows applications to define new option types. | |
482 | The \fIcustomPtr\fR field of the entry points to a structure | |
483 | defining the new option type. | |
484 | See the section CUSTOM OPTION TYPES below for details. | |
485 | .TP | |
486 | \fBTK_CONFIG_DOUBLE\fR | |
487 | The value must be an ASCII floating-point number in | |
488 | the format accepted by \fBstrtol\fR. The string is converted | |
489 | to a \fBdouble\fR value, and the value is stored in the | |
490 | target. | |
491 | .TP | |
492 | \fBTK_CONFIG_END\fR | |
493 | Marks the end of the table. The last entry in \fIspecs\fR | |
494 | must have this type; all of its other fields are ignored and it | |
495 | will never match any arguments. | |
496 | .TP | |
497 | \fBTK_CONFIG_FONT\fR | |
498 | The value must be an ASCII string identifying a font in a form | |
499 | suitable for passing to \fBTk_GetFont\fR. The value is converted | |
500 | to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result | |
501 | is stored in the target. | |
502 | If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value | |
503 | may be an empty string, in which case the target will be set to NULL. | |
504 | If the previous value of the target | |
505 | wasn't NULL, then it is freed by passing it to \fBTk_FreeFont\fR. | |
506 | .TP | |
507 | \fBTK_CONFIG_INT\fR | |
508 | The value must be an ASCII integer string | |
509 | in the format accepted by \fBstrtol\fR (e.g. ``0'' | |
510 | and ``0x'' prefixes may be used to specify octal or hexadecimal | |
511 | numbers, respectively). The string is converted to an integer | |
512 | value and the integer is stored in the target. | |
513 | .TP | |
514 | \fBTK_CONFIG_JOIN_STYLE\fR | |
515 | The value must be | |
516 | an ASCII string identifying a join style in one of the ways | |
517 | accepted by \fBTk_GetJoinStyle\fR. | |
518 | The string is converted to an integer value corresponding | |
519 | to the join style by calling | |
520 | \fBTk_GetJoinStyle\fR and the result is stored in the target. | |
521 | .TP | |
522 | \fBTK_CONFIG_JUSTIFY\fR | |
523 | The value must be | |
524 | an ASCII string identifying a justification method in one of the | |
525 | ways accepted by \fBTk_GetJustify\fR. | |
526 | The string is converted to a \fBTk_Justify\fR by calling | |
527 | \fBTk_GetJustify\fR and the result is stored in the target. | |
528 | .TP | |
529 | \fBTK_CONFIG_MM\fR | |
530 | The value must specify a screen distance in one of the forms acceptable | |
531 | to \fBTk_GetScreenMM\fR. | |
532 | The string is converted to double-precision floating-point distance | |
533 | in millimeters and the value is stored in the target. | |
534 | .TP | |
535 | \fBTK_CONFIG_PIXELS\fR | |
536 | The value must specify screen units in one of the forms acceptable | |
537 | to \fBTk_GetPixels\fR. | |
538 | The string is converted to an integer distance in pixels and the | |
539 | value is stored in the target. | |
540 | .TP | |
541 | \fBTK_CONFIG_RELIEF\fR | |
542 | The value must be an ASCII string identifying a relief in a form | |
543 | suitable for passing to \fBTk_GetRelief\fR. The value is converted | |
544 | to an integer relief value by calling \fBTk_GetRelief\fR and the result | |
545 | is stored in the target. | |
546 | .TP | |
547 | \fBTK_CONFIG_STRING\fR | |
548 | A copy | |
549 | of the value is made by allocating memory space with | |
550 | \fBmalloc\fR and copying the value into the dynamically-allocated | |
551 | space. A pointer to the new string is stored in the target. | |
552 | If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value | |
553 | may be an empty string, in which case the target will be set to NULL. | |
554 | If the previous value of the target wasn't NULL, then it is | |
555 | freed by passing it to \fBfree\fR. | |
556 | .TP | |
557 | \fBTK_CONFIG_SYNONYM\fR | |
558 | This \fItype\fR value identifies special entries in \fIspecs\fR that | |
559 | are synonyms for other entries. If an \fIargv\fR value matches the | |
560 | \fIargvName\fR of a TK_CONFIG_SYNONYM entry, the entry isn't used | |
561 | directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR | |
562 | for another entry whose \fIargvName\fR is the same as the \fIdbName\fR | |
563 | field in the TK_CONFIG_SYNONYM entry; this new entry is used just | |
564 | as if its \fIargvName\fR had matched the \fIargv\fR value. The | |
565 | synonym mechanism allows multiple \fIargv\fR values to be used for | |
566 | a single configuration option, such as ``\-background'' and ``\-bg''. | |
567 | .TP | |
568 | \fBTK_CONFIG_UID\fR | |
569 | The value is translated to a \fBTk_Uid\fR | |
570 | (by passing it to \fBTk_GetUid\fR). The resulting value | |
571 | is stored in the target. | |
572 | If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR and the value | |
573 | is an empty string then the target will be set to NULL. | |
574 | .TP | |
575 | \fBTK_CONFIG_WINDOW\fR | |
576 | The value must be a window path name. It is translated to a | |
577 | \fBTk_Window\fR token and the token is stored in the target. | |
578 | ||
579 | .SH "GROUPED ENTRIES" | |
580 | .PP | |
581 | In some cases it is useful to generate multiple resources from | |
582 | a single configuration value. For example, a color name might | |
583 | be used both to generate the background color for a widget (using | |
584 | TK_CONFIG_COLOR) and to generate a 3-D border to draw around the | |
585 | widget (using TK_CONFIG_BORDER). In cases like this it is possible | |
586 | to specify that several consecutive entries in \fIspecs\fR are to | |
587 | be treated as a group. The first entry is used to determine a value | |
588 | (using its \fIargvName\fR, \fIdbName\fR, | |
589 | \fIdbClass\fR, and \fIdefValue\fR fields). The value will be processed | |
590 | several times (one for each entry in the group), generating multiple | |
591 | different resources and modifying multiple targets within \fIwidgRec\fR. | |
592 | Each of the entries after the first must have a NULL value in its | |
593 | \fIargvName\fR field; this indicates that the entry is to be grouped | |
594 | with the entry that precedes it. Only the \fItype\fR and \fIoffset\fR | |
595 | fields are used from these follow-on entries. | |
596 | ||
597 | .SH "FLAGS" | |
598 | .PP | |
599 | The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used | |
600 | in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR | |
601 | to provide additional control over the processing of configuration | |
602 | options. These values are used in three different ways as | |
603 | described below. | |
604 | .PP | |
605 | First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has | |
606 | the TK_CONFIG_ARGV_ONLY bit set (i.e., \fIflags\fR | TK_CONFIG_ARGV_ONLY != 0), | |
607 | then the option database and | |
608 | \fIdefValue\fR fields are not used. In this case, if an entry in | |
609 | \fIspecs\fR doesn't match a field in \fIargv\fR then nothing happens: | |
610 | the corresponding target isn't modified. This feature is useful | |
611 | when the goal is to modify certain configuration options while | |
612 | leaving others in their current state, such as when a \fBconfigure\fR | |
613 | widget command is being processed. | |
614 | .PP | |
615 | Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used | |
616 | to control the processing of that entry. Each \fIspecFlags\fR | |
617 | field may consists of an OR-ed combination of the following values: | |
618 | .TP | |
619 | \fBTK_CONFIG_COLOR_ONLY\fR | |
620 | If this bit is set then the entry will only be considered if the | |
621 | display for \fItkwin\fR has more than one bit plane. If the display | |
622 | is monochromatic then this \fIspecs\fR entry will be ignored. | |
623 | .TP | |
624 | \fBTK_CONFIG_MONO_ONLY\fR | |
625 | If this bit is set then the entry will only be considered if the | |
626 | display for \fItkwin\fR has exactly one bit plane. If the display | |
627 | is not monochromatic then this \fIspecs\fR entry will be ignored. | |
628 | .TP | |
629 | \fBTK_CONFIG_NULL_OK\fR | |
630 | This bit is only relevant for some types of entries (see the | |
631 | descriptions of the various entry types above). | |
632 | If this bit is set, it indicates that an empty string value | |
633 | for the field is acceptable and if it occurs then the | |
634 | target should be set to NULL or \fBNone\fR, depending | |
635 | on the type of the target. | |
636 | This flag is typically used to allow a | |
637 | feature to be turned off entirely, e.g. set a cursor value to | |
638 | \fBNone\fR so that a window simply inherits its parent's cursor. | |
639 | If this bit isn't set then empty strings are processed as strings, | |
640 | which generally results in an error. | |
641 | .TP | |
642 | \fBTK_CONFIG_DONT_SET_DEFAULT\fR | |
643 | If this bit is one, it means that the \fIdefValue\fR field of the | |
644 | entry should only be used for returning the default value in | |
645 | \fBTk_ConfigureInfo\fR. | |
646 | In calls to \fBTk_ConfigureWidget\fR no default will be supplied | |
647 | for entries with this flag set; it is assumed that the | |
648 | caller has already supplied a default value in the target location. | |
649 | This flag provides a performance optimization where it is expensive | |
650 | to process the default string: the client can compute the default | |
651 | once, save the value, and provide it before calling | |
652 | \fBTk_ConfigureWidget\fR. | |
653 | .TP | |
654 | \fBTK_CONFIG_OPTION_SPECIFIED\fR | |
655 | This bit is set and cleared by \fBTk_ConfigureWidget\fR. Whenever | |
656 | \fBTk_ConfigureWidget\fR returns, this bit will be set in all the | |
657 | entries where a value was specified in \fIargv\fR. | |
658 | It will be zero in all other entries. | |
659 | This bit provides a way for clients to determine which values | |
660 | actually changed in a call to \fBTk_ConfigureWidget\fR. | |
661 | .PP | |
662 | The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically | |
663 | used to specify different default values for | |
664 | monochrome and color displays. This is done by creating two | |
665 | entries in \fIspecs\fR that are identical except for their | |
666 | \fIdefValue\fR and \fIspecFlags\fR fields. One entry should have | |
667 | the value TK_CONFIG_MONO_ONLY in its \fIspecFlags\fR and the | |
668 | default value for monochrome displays in its \fIdefValue\fR; the | |
669 | other entry entry should have the value TK_CONFIG_COLOR_ONLY in | |
670 | its \fIspecFlags\fR and the appropriate \fIdefValue\fR for | |
671 | color displays. | |
672 | .PP | |
673 | Third, it is possible to use \fIflags\fR and \fIspecFlags\fR | |
674 | together to selectively disable some entries. This feature is | |
675 | not needed very often. It is useful in cases where several | |
676 | similar kinds of widgets are implemented in one place. It allows | |
677 | a single \fIspecs\fR table to be created with all the configuration | |
678 | options for all the widget types. When processing a particular | |
679 | widget type, only entries relevant to that type will be used. This | |
680 | effect is achieved by setting the high-order bits (those in positions | |
681 | equal to or greater than TK_CONFIG_USER_BIT) in \fIspecFlags\fR | |
682 | values or in \fIflags\fR. In order for a particular entry in | |
683 | \fIspecs\fR to be used, its high-order bits must match exactly | |
684 | the high-order bits of the \fIflags\fR value passed to | |
685 | \fBTk_ConfigureWidget\fR. If a \fIspecs\fR table is being used | |
686 | for N different widget types, then N of the high-order bits will | |
687 | be used. Each \fIspecs\fR entry will have one of more of those | |
688 | bits set in its \fIspecFlags\fR field to indicate the widget types | |
689 | for which this entry is valid. When calling \fBTk_ConfigureWidget\fR, | |
690 | \fIflags\fR will have a single one of these bits set to select the | |
691 | entries for the desired widget type. For a working example of | |
692 | this feature, see the code in tkButton.c. | |
693 | ||
694 | .SH TK_OFFSET | |
695 | .PP | |
696 | The \fBTk_Offset\fR macro is provided as a safe way of generating | |
697 | the \fIoffset\fR values for entries in Tk_ConfigSpec structures. | |
698 | It takes two arguments: the name of a type of record, and the | |
699 | name of a field in that record. It returns the byte offset of | |
700 | the named field in records of the given type. | |
701 | ||
702 | .SH TK_CONFIGUREINFO | |
703 | .PP | |
704 | The \fBTk_ConfigureInfo\fR procedure may be used to obtain | |
705 | information about one or all of the options for a given widget. | |
706 | Given a token for a window (\fItkwin\fR), a table describing the | |
707 | configuration options for a class of widgets (\fIspecs\fR), a | |
708 | pointer to a widget record containing the current information for | |
709 | a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument, | |
710 | \fBTk_ConfigureInfo\fR generates a string describing all of the | |
711 | configuration options for the window. The string is placed | |
712 | in \fIinterp->result\fR. Under normal circumstances | |
713 | it returns TCL_OK; if an error occurs then it returns TCL_ERROR | |
714 | and \fIinterp->result\fR contains an error message. | |
715 | .PP | |
716 | If \fIargvName\fR is NULL, then the value left in | |
717 | \fIinterp->result\fR by \fBTk_ConfigureInfo\fR | |
718 | consists of a list of one or more entries, each of which describes | |
719 | one configuration option (i.e. one entry in \fIspecs\fR). Each | |
720 | entry in the list will contain either two or five values. If the | |
721 | corresponding entry in \fIspecs\fR has type TK_CONFIG_SYNONYM, then | |
722 | the list will contain two values: the \fIargvName\fR for the entry | |
723 | and the \fIdbName\fR (synonym name). Otherwise the list will contain | |
724 | five values: \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR, | |
725 | and current value. The current value is computed from the appropriate | |
726 | field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR. | |
727 | .PP | |
728 | If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL, | |
729 | then it indicates a single option, and information is returned only | |
730 | for that option. The string placed in \fIinterp->result\fR will be | |
731 | a list containing two or five values as described above; this will | |
732 | be identical to the corresponding sublist that would have been returned | |
733 | if \fIargvName\fR had been NULL. | |
734 | .PP | |
735 | The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict | |
736 | the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR. | |
737 | ||
738 | .SH TK_CONFIGUREVALUE | |
739 | .PP | |
740 | \fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR; | |
741 | instead of returning a list of values, it just returns the current value | |
742 | of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL). | |
743 | The value is returned in \fIinterp->result\fR and TCL_OK is | |
744 | normally returned as the procedure's result. | |
745 | If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is | |
746 | not a valid option name), TCL_ERROR is returned and an error message | |
747 | is left in \fIinterp->result\fR. | |
748 | This procedure is typically called to implement \fBcget\fR widget | |
749 | commands. | |
750 | ||
751 | .SH TK_FREEOPTIONS | |
752 | .PP | |
753 | The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup | |
754 | to release all of the resources associated with configuration options. | |
755 | It scans through \fIspecs\fR and for each entry corresponding to a | |
756 | resource that must be explicitly freed (e.g. those with | |
757 | type TK_CONFIG_COLOR), it frees the resource in the widget record. | |
758 | If the field in the widget record doesn't refer to a resource (e.g. | |
759 | it contains a null pointer) then no resource is freed for that | |
760 | entry. | |
761 | After freeing a resource, \fBTk_FreeOptions\fR sets the | |
762 | corresponding field of the widget record to null. | |
763 | ||
764 | .SH "CUSTOM OPTION TYPES" | |
765 | .PP | |
766 | Applications can extend the built-in configuration types with additional | |
767 | configuration types by writing procedures to parse and print options | |
768 | of the a type and creating a structure pointing to those procedures: | |
769 | .CS | |
770 | typedef struct Tk_CustomOption { | |
771 | Tk_OptionParseProc *\fIparseProc\fR; | |
772 | Tk_OptionPrintProc *\fIprintProc\fR; | |
773 | ClientData \fIclientData\fR; | |
774 | } Tk_CustomOption; | |
775 | ||
776 | typedef int Tk_OptionParseProc( | |
777 | ClientData \fIclientData\fR, | |
778 | Tcl_Interp *\fIinterp\fR, | |
779 | Tk_Window \fItkwin\fR, | |
780 | char *\fIvalue\fR, | |
781 | char *\fIwidgRec\fR, | |
782 | int \fIoffset\fR); | |
783 | ||
784 | typedef char *Tk_OptionPrintProc( | |
785 | ClientData \fIclientData\fR, | |
786 | Tk_Window \fItkwin\fR, | |
787 | char *\fIwidgRec\fR, | |
788 | int \fIoffset\fR, | |
789 | Tcl_FreeProc **\fIfreeProcPtr\fR); | |
790 | .CE | |
791 | The Tk_CustomOption structure contains three fields, which are pointers | |
792 | to the two procedures and a \fIclientData\fR value to be passed to those | |
793 | procedures when they are invoked. The \fIclientData\fR value typically | |
794 | points to a structure containing information that is needed by the | |
795 | procedures when they are parsing and printing options. | |
796 | .PP | |
797 | The \fIparseProc\fR procedure is invoked by | |
798 | \fBTk_ConfigureWidget\fR to parse a string and store the resulting | |
799 | value in the widget record. | |
800 | The \fIclientData\fR argument is a copy of the \fIclientData\fR | |
801 | field in the Tk_CustomOption structure. | |
802 | The \fIinterp\fR argument points to a Tcl interpreter used for | |
803 | error reporting. \fITkwin\fR is a copy of the \fItkwin\fR argument | |
804 | to \fBTk_ConfigureWidget\fR. The \fIvalue\fR argument is a string | |
805 | describing the value for the option; it could have been specified | |
806 | explicitly in the call to \fBTk_ConfigureWidget\fR or it could | |
807 | come from the option database or a default. | |
808 | \fIValue\fR will never be a null pointer but it may point to | |
809 | an empty string. | |
810 | \fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to | |
811 | \fBTk_ConfigureWidget\fR; it points to the start of the widget | |
812 | record to modify. | |
813 | The last argument, \fIoffset\fR, gives the offset in bytes from the start | |
814 | of the widget record to the location where the option value is to | |
815 | be placed. The procedure should translate the string to whatever | |
816 | form is appropriate for the option and store the value in the widget | |
817 | record. It should normally return TCL_OK, but if an error occurs | |
818 | in translating the string to a value then it should return TCL_ERROR | |
819 | and store an error message in \fIinterp->result\fR. | |
820 | .PP | |
821 | The \fIprintProc\fR procedure is called | |
822 | by \fBTk_ConfigureInfo\fR to produce a string value describing an | |
823 | existing option. | |
824 | Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR | |
825 | arguments all have the same meaning as for Tk_OptionParseProc | |
826 | procedures. | |
827 | The \fIprintProc\fR procedure should examine the option whose value | |
828 | is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing | |
829 | that option, and return a pointer to the string. | |
830 | If the string is stored in dynamically-allocated memory, then | |
831 | the procedure must set \fI*freeProcPtr\fR to the address of | |
832 | a procedure to call to free the string's memory; \fBTk_ConfigureInfo\fR | |
833 | will call this procedure when it is finished with the string. | |
834 | If the result string is stored in static memory then \fIprintProc\fR | |
835 | need not do anything with the \fIfreeProcPtr\fR argument. | |
836 | .PP | |
837 | Once \fIparseProc\fR and \fIprintProc\fR have been defined and a | |
838 | Tk_CustomOption structure has been created for them, options of this | |
839 | new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR | |
840 | fields are TK_CONFIG_CUSTOM and whose \fIcustomPtr\fR fields point | |
841 | to the Tk_CustomOption structure. | |
842 | ||
843 | .SH EXAMPLES | |
844 | .PP | |
845 | Although the explanation of \fBTk_ConfigureWidget\fR is fairly | |
846 | complicated, its actual use is pretty straightforward. | |
847 | The easiest way to get started is to copy the code | |
848 | from an existing widget. | |
849 | The library implementation of frames | |
850 | (tkFrame.c) has a simple configuration table, and the library | |
851 | implementation of buttons (tkButton.c) has a much more complex | |
852 | table that uses many of the fancy \fIspecFlags\fR mechanisms. | |
853 | ||
854 | .SH "SEE ALSO" | |
855 | Tk_SetOptions(3) | |
856 | ||
857 | .SH KEYWORDS | |
858 | anchor, bitmap, boolean, border, cap style, color, configuration options, | |
859 | cursor, custom, double, font, integer, join style, justify, millimeters, | |
860 | pixels, relief, synonym, uid |