Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1998 Sun Microsystems, Inc. | |
3 | '\" | |
4 | '\" See the file "license.terms" for information on usage and redistribution | |
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
6 | '\" | |
7 | '\" RCS: @(#) $Id: SetOptions.3,v 1.8 2000/10/01 21:31:35 ericm Exp $ | |
8 | '\" | |
9 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
10 | '\" manual entries. | |
11 | '\" | |
12 | '\" .AP type name in/out ?indent? | |
13 | '\" Start paragraph describing an argument to a library procedure. | |
14 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
15 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
16 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
17 | '\" needed; use .AS below instead) | |
18 | '\" | |
19 | '\" .AS ?type? ?name? | |
20 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
21 | '\" name are examples of largest possible arguments that will be passed | |
22 | '\" to .AP later. If args are omitted, default tab stops are used. | |
23 | '\" | |
24 | '\" .BS | |
25 | '\" Start box enclosure. From here until next .BE, everything will be | |
26 | '\" enclosed in one large box. | |
27 | '\" | |
28 | '\" .BE | |
29 | '\" End of box enclosure. | |
30 | '\" | |
31 | '\" .CS | |
32 | '\" Begin code excerpt. | |
33 | '\" | |
34 | '\" .CE | |
35 | '\" End code excerpt. | |
36 | '\" | |
37 | '\" .VS ?version? ?br? | |
38 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
39 | '\" of man pages. The first argument is ignored and used for recording | |
40 | '\" the version when the .VS was added, so that the sidebars can be | |
41 | '\" found and removed when they reach a certain age. If another argument | |
42 | '\" is present, then a line break is forced before starting the sidebar. | |
43 | '\" | |
44 | '\" .VE | |
45 | '\" End of vertical sidebar. | |
46 | '\" | |
47 | '\" .DS | |
48 | '\" Begin an indented unfilled display. | |
49 | '\" | |
50 | '\" .DE | |
51 | '\" End of indented unfilled display. | |
52 | '\" | |
53 | '\" .SO | |
54 | '\" Start of list of standard options for a Tk widget. The | |
55 | '\" options follow on successive lines, in four columns separated | |
56 | '\" by tabs. | |
57 | '\" | |
58 | '\" .SE | |
59 | '\" End of list of standard options for a Tk widget. | |
60 | '\" | |
61 | '\" .OP cmdName dbName dbClass | |
62 | '\" Start of description of a specific option. cmdName gives the | |
63 | '\" option's name as specified in the class command, dbName gives | |
64 | '\" the option's name in the option database, and dbClass gives | |
65 | '\" the option's class in the option database. | |
66 | '\" | |
67 | '\" .UL arg1 arg2 | |
68 | '\" Print arg1 underlined, then print arg2 normally. | |
69 | '\" | |
70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
71 | '\" | |
72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
73 | .if t .wh -1.3i ^B | |
74 | .nr ^l \n(.l | |
75 | .ad b | |
76 | '\" # Start an argument description | |
77 | .de AP | |
78 | .ie !"\\$4"" .TP \\$4 | |
79 | .el \{\ | |
80 | . ie !"\\$2"" .TP \\n()Cu | |
81 | . el .TP 15 | |
82 | .\} | |
83 | .ta \\n()Au \\n()Bu | |
84 | .ie !"\\$3"" \{\ | |
85 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
86 | .\".b | |
87 | .\} | |
88 | .el \{\ | |
89 | .br | |
90 | .ie !"\\$2"" \{\ | |
91 | \&\\$1 \\fI\\$2\\fP | |
92 | .\} | |
93 | .el \{\ | |
94 | \&\\fI\\$1\\fP | |
95 | .\} | |
96 | .\} | |
97 | .. | |
98 | '\" # define tabbing values for .AP | |
99 | .de AS | |
100 | .nr )A 10n | |
101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
102 | .nr )B \\n()Au+15n | |
103 | .\" | |
104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
106 | .. | |
107 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
108 | '\" # BS - start boxed text | |
109 | '\" # ^y = starting y location | |
110 | '\" # ^b = 1 | |
111 | .de BS | |
112 | .br | |
113 | .mk ^y | |
114 | .nr ^b 1u | |
115 | .if n .nf | |
116 | .if n .ti 0 | |
117 | .if n \l'\\n(.lu\(ul' | |
118 | .if n .fi | |
119 | .. | |
120 | '\" # BE - end boxed text (draw box now) | |
121 | .de BE | |
122 | .nf | |
123 | .ti 0 | |
124 | .mk ^t | |
125 | .ie n \l'\\n(^lu\(ul' | |
126 | .el \{\ | |
127 | .\" Draw four-sided box normally, but don't draw top of | |
128 | .\" box if the box started on an earlier page. | |
129 | .ie !\\n(^b-1 \{\ | |
130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
131 | .\} | |
132 | .el \}\ | |
133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
134 | .\} | |
135 | .\} | |
136 | .fi | |
137 | .br | |
138 | .nr ^b 0 | |
139 | .. | |
140 | '\" # VS - start vertical sidebar | |
141 | '\" # ^Y = starting y location | |
142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
143 | .de VS | |
144 | .if !"\\$2"" .br | |
145 | .mk ^Y | |
146 | .ie n 'mc \s12\(br\s0 | |
147 | .el .nr ^v 1u | |
148 | .. | |
149 | '\" # VE - end of vertical sidebar | |
150 | .de VE | |
151 | .ie n 'mc | |
152 | .el \{\ | |
153 | .ev 2 | |
154 | .nf | |
155 | .ti 0 | |
156 | .mk ^t | |
157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
158 | .sp -1 | |
159 | .fi | |
160 | .ev | |
161 | .\} | |
162 | .nr ^v 0 | |
163 | .. | |
164 | '\" # Special macro to handle page bottom: finish off current | |
165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
166 | '\" # page bottom macro. | |
167 | .de ^B | |
168 | .ev 2 | |
169 | 'ti 0 | |
170 | 'nf | |
171 | .mk ^t | |
172 | .if \\n(^b \{\ | |
173 | .\" Draw three-sided box if this is the box's first page, | |
174 | .\" draw two sides but no top otherwise. | |
175 | .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 | |
176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
177 | .\} | |
178 | .if \\n(^v \{\ | |
179 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
181 | .\} | |
182 | .bp | |
183 | 'fi | |
184 | .ev | |
185 | .if \\n(^b \{\ | |
186 | .mk ^y | |
187 | .nr ^b 2 | |
188 | .\} | |
189 | .if \\n(^v \{\ | |
190 | .mk ^Y | |
191 | .\} | |
192 | .. | |
193 | '\" # DS - begin display | |
194 | .de DS | |
195 | .RS | |
196 | .nf | |
197 | .sp | |
198 | .. | |
199 | '\" # DE - end display | |
200 | .de DE | |
201 | .fi | |
202 | .RE | |
203 | .sp | |
204 | .. | |
205 | '\" # SO - start of list of standard options | |
206 | .de SO | |
207 | .SH "STANDARD OPTIONS" | |
208 | .LP | |
209 | .nf | |
210 | .ta 5.5c 11c | |
211 | .ft B | |
212 | .. | |
213 | '\" # SE - end of list of standard options | |
214 | .de SE | |
215 | .fi | |
216 | .ft R | |
217 | .LP | |
218 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
219 | .. | |
220 | '\" # OP - start of full description for a single option | |
221 | .de OP | |
222 | .LP | |
223 | .nf | |
224 | .ta 4c | |
225 | Command-Line Name: \\fB\\$1\\fR | |
226 | Database Name: \\fB\\$2\\fR | |
227 | Database Class: \\fB\\$3\\fR | |
228 | .fi | |
229 | .IP | |
230 | .. | |
231 | '\" # CS - begin code excerpt | |
232 | .de CS | |
233 | .RS | |
234 | .nf | |
235 | .ta .25i .5i .75i 1i | |
236 | .. | |
237 | '\" # CE - end code excerpt | |
238 | .de CE | |
239 | .fi | |
240 | .RE | |
241 | .. | |
242 | .de UL | |
243 | \\$1\l'|0\(ul'\\$2 | |
244 | .. | |
245 | .TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures" | |
246 | .BS | |
247 | .SH NAME | |
248 | Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options | |
249 | .SH SYNOPSIS | |
250 | .nf | |
251 | \fB#include <tk.h>\fR | |
252 | .sp | |
253 | Tk_OptionTable | |
254 | \fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR | |
255 | .sp | |
256 | \fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR | |
257 | .sp | |
258 | int | |
259 | \fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR | |
260 | .sp | |
261 | int | |
262 | \fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR | |
263 | .sp | |
264 | \fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR | |
265 | .sp | |
266 | \fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR | |
267 | .sp | |
268 | Tcl_Obj * | |
269 | \fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR | |
270 | .sp | |
271 | Tcl_Obj * | |
272 | \fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR | |
273 | .sp | |
274 | \fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR | |
275 | .sp | |
276 | int | |
277 | \fBTk_Offset(\fItype, field\fB)\fR | |
278 | .SH ARGUMENTS | |
279 | .AS Tk_SavedOptions "*CONST objv[]" in/out | |
280 | .AP Tcl_Interp *interp in | |
281 | A Tcl interpreter. Most procedures use this only for returning error | |
282 | messages; if it is NULL then no error messages are returned. For | |
283 | \fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the | |
284 | interpreter in which the option table will be used. | |
285 | .AP Tk_OptionSpec *templatePtr in | |
286 | Points to an array of static information that describes the configuration | |
287 | options that are supported. Used to build a Tk_OptionTable. The information | |
288 | pointed to by this argument must exist for the lifetime of the Tk_OptionTable. | |
289 | .AP Tk_OptionTable optionTable in | |
290 | Token for an option table. Must have been returned by a previous call | |
291 | to \fBTk_CreateOptionTable\fR. | |
292 | .AP char *recordPtr in/out | |
293 | Points to structure in which values of configuration options are stored; | |
294 | fields of this record are modified by procedures such as \fBTk_SetOptions\fR | |
295 | and read by procedures such as \fBTk_GetOptionValue\fR. | |
296 | .AP Tk_Window tkwin in | |
297 | For options such as TK_OPTION_COLOR, this argument indicates | |
298 | the window in which the option will be used. If \fIoptionTable\fR uses | |
299 | no window-dependent options, then a NULL value may be supplied for | |
300 | this argument. | |
301 | .AP int objc in | |
302 | Number of values in \fIobjv\fR. | |
303 | .AP Tcl_Obj "*CONST objv[]" in | |
304 | Command-line arguments for setting configuring options. | |
305 | .AP Tk_SavedOptions *savePtr out | |
306 | If not NULL, the structure pointed to by this argument is filled | |
307 | in with the old values of any options that were modified and old | |
308 | values are restored automatically if an error occurs in \fBTk_SetOptions\fR. | |
309 | .AP int *maskPtr out | |
310 | If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the | |
311 | bit-wise OR of the \fItypeMask\fR fields for the options that | |
312 | were modified. | |
313 | .AP Tk_SavedOptions *savedPtr in/out | |
314 | Points to a structure previously filled in by \fBTk_SetOptions\fR with | |
315 | old values of modified options. | |
316 | .AP Tcl_Obj *namePtr in | |
317 | The value of this object is the name of a particular option. If NULL | |
318 | is passed to \fBTk_GetOptionInfo\fR then information is returned for | |
319 | all options. Must not be NULL when \fBTk_GetOptionValue\fR is called. | |
320 | .AP "type name" type in | |
321 | The name of the type of a record. | |
322 | .AP "field name" field in | |
323 | The name of a field in records of type \fItype\fR. | |
324 | .BE | |
325 | .SH DESCRIPTION | |
326 | .PP | |
327 | These procedures handle most of the details of parsing configuration | |
328 | options such as those for Tk widgets. Given a description of what | |
329 | options are supported, these procedures handle all the details of | |
330 | parsing options and storing their values into a C structure associated | |
331 | with the widget or object. The procedures were designed primarily for | |
332 | widgets in Tk, but they can also be used for other kinds of objects that | |
333 | have configuration options. In the rest of this manual page ``widget'' will | |
334 | be used to refer to the object whose options are being managed; in | |
335 | practice the object may not actually be a widget. The term ``widget | |
336 | record'' is used to refer to the C-level structure in | |
337 | which information about a particular widget or object is stored. | |
338 | .PP | |
339 | Note: the easiest way to learn how to use these procedures is to | |
340 | look at a working example. In Tk, the simplest example is the code | |
341 | that implements the button family of widgets, which is an \fBtkButton.c\fR. | |
342 | Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR. | |
343 | .PP | |
344 | In order to use these procedures, the code that implements the widget | |
345 | must contain a static array of Tk_OptionSpec structures. This is a | |
346 | template that describes the various options supported by that class of | |
347 | widget; there is a separate template for each kind of widget. The | |
348 | template contains information such as the name of each option, its type, | |
349 | its default value, and where the value of the option is stored in the | |
350 | widget record. See TEMPLATES below for more detail. | |
351 | .PP | |
352 | In order to process configuration options efficiently, the static | |
353 | template must be augmented with additional information that is available | |
354 | only at runtime. The procedure \fBTk_CreateOptionTable\fR creates this | |
355 | dynamic information from the template and returns a Tk_OptionTable token | |
356 | that describes both the static and dynamic information. All of the | |
357 | other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable | |
358 | token as argument. Typically, \fBTk_CreateOptionTable\fR is called the | |
359 | first time that a widget of a particular class is created and the | |
360 | resulting Tk_OptionTable is used in the future for all widgets of that | |
361 | class. A Tk_OptionTable may be used only in a single interpreter, given | |
362 | by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR. When an | |
363 | option table is no longer needed \fBTk_DeleteOptionTable\fR should be | |
364 | called to free all of its resources. All of the option tables | |
365 | for a Tcl interpreter are freed automatically if the interpreter is deleted. | |
366 | .PP | |
367 | \fBTk_InitOptions\fR is invoked when a new widget is created to set | |
368 | the default values for all of the widget's configuration options. | |
369 | \fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR) | |
370 | and a pointer to a widget record (\fIrecordPtr\fR), which is the C | |
371 | structure that holds information about this widget. \fBTk_InitOptions\fR | |
372 | uses the information in the option table to | |
373 | choose an appropriate default for each option, then it stores the default | |
374 | value directly into the widget record, overwriting any information that | |
375 | was already present in the widget record. \fBTk_InitOptions\fR normally | |
376 | returns TCL_OK. If an error occurred while setting the default values | |
377 | (e.g., because a default value was erroneous) then TCL_ERROR is returned | |
378 | and an error message is left in \fIinterp\fR's result if \fIinterp\fR | |
379 | isn't NULL. | |
380 | .PP | |
381 | \fBTk_SetOptions\fR is invoked to modify configuration options based | |
382 | on information specified in a Tcl command. The command might be one that | |
383 | creates a new widget, or a command that modifies options on an existing | |
384 | widget. The \fIobjc\fR and \fIobjv\fR arguments describe the | |
385 | values of the arguments from the Tcl command. \fIObjv\fR must contain | |
386 | an even number of objects: the first object of each pair gives the name of | |
387 | an option and the second object gives the new value for that option. | |
388 | \fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that | |
389 | the new value of the option conforms to the type in \fIoptionTable\fR, | |
390 | and stores the value of the option into the widget record given by | |
391 | \fIrecordPtr\fR. \fBTk_SetOptions\fR normally returns TCL_OK. If | |
392 | an error occurred (such as an unknown option name or an illegal option | |
393 | value) then TCL_ERROR is returned and an error message is left in | |
394 | \fIinterp\fR's result if \fIinterp\fR isn't NULL. | |
395 | .PP | |
396 | \fBTk_SetOptions\fR has two additional features. First, if the | |
397 | \fImaskPtr\fR argument isn't NULL then it points to an integer | |
398 | value that is filled in with information about the options that were | |
399 | modified. For each option in the template passed to | |
400 | \fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field. The | |
401 | bits of this field are defined by the code that implements the widget; | |
402 | for example, each bit might correspond to a particular configuration option. | |
403 | Alternatively, bits might be used functionally. For example, one bit might | |
404 | be used for redisplay: all options that affect the widget's display, such | |
405 | that changing the option requires the widget to be redisplayed, might have | |
406 | that bit set. Another bit might indicate that the geometry of the widget | |
407 | must be recomputed, and so on. \fBTk_SetOptions\fR OR's together the | |
408 | \fItypeMask\fR fields from all the options that were modified and returns | |
409 | this value at *\fImaskPtr\fR; the caller can then use this information | |
410 | to optimize itself so that, for example, it doesn't redisplay the widget | |
411 | if the modified options don't affect the widget's appearance. | |
412 | .PP | |
413 | The second additional feature of \fBTk_SetOptions\fR has to do with error | |
414 | recovery. If an error occurs while processing configuration options, this | |
415 | feature makes it possible to restore all the configuration options to their | |
416 | previous values. Errors can occur either while processing options in | |
417 | \fBTk_SetOptions\fR or later in the caller. In many cases the caller does | |
418 | additional processing after \fBTk_SetOptions\fR returns; for example, it | |
419 | might use an option value to set a trace on a variable and may detect | |
420 | an error if the variable is an array instead of a scalar. Error recovery | |
421 | is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument | |
422 | to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized | |
423 | Tk_SavedOptions structure on the caller's stack. \fBTk_SetOptions\fR | |
424 | overwrites the structure pointed to by \fIsavePtr\fR with information | |
425 | about the old values of any options modified by the procedure. | |
426 | If \fBTk_SetOptions\fR returns successfully, the | |
427 | caller uses the structure in one of two ways. If the caller completes | |
428 | its processing of the new options without any errors, then it must pass | |
429 | the structure to \fBTk_FreeSavedOptions\fR so that the old values can be | |
430 | freed. If the caller detects an error in its processing of the new | |
431 | options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR, | |
432 | which will copy the old values back into the widget record and free | |
433 | the new values. | |
434 | If \fBTk_SetOptions\fR detects an error then it automatically restores | |
435 | any options that had already been modified and leaves *\fIsavePtr\fR in | |
436 | an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or | |
437 | \fBTk_RestoreSavedOptions\fR. | |
438 | If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then | |
439 | \fBTk_SetOptions\fR frees each old option value immediately when it sets a new | |
440 | value for the option. In this case, if an error occurs in the third | |
441 | option, the old values for the first two options cannot be restored. | |
442 | .PP | |
443 | \fBTk_GetOptionValue\fR returns the current value of a configuration option | |
444 | for a particular widget. The \fInamePtr\fR argument contains the name of | |
445 | an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR | |
446 | to lookup the option and extract its value from the widget record | |
447 | pointed to by \fIrecordPtr\fR, then it returns an object containing | |
448 | that value. If an error occurs (e.g., because \fInamePtr\fR contains an | |
449 | unknown option name) then NULL is returned and an error message is left | |
450 | in \fIinterp\fR's result unless \fIinterp\fR is NULL. | |
451 | .PP | |
452 | \fBTk_GetOptionInfo\fR returns information about configuration options in | |
453 | a form suitable for \fBconfigure\fR widget commands. If the \fInamePtr\fR | |
454 | argument is not NULL, it points to an object that gives the name of a | |
455 | configuration option; \fBTk_GetOptionInfo\fR returns an object containing | |
456 | a list with five elements, which are the name of the option, the name and | |
457 | class used for the option in the option database, the default value for | |
458 | the option, and the current value for the option. If the \fInamePtr\fR | |
459 | argument is NULL, then \fBTk_GetOptionInfo\fR returns information about | |
460 | all options in the form of a list of lists; each sublist describes one | |
461 | option. Synonym options are handled differently depending on whether | |
462 | \fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for | |
463 | each synonym option has only two elements, which are the name of the | |
464 | option and the name of the other option that it refers to; if \fInamePtr\fR | |
465 | is non-NULL and names a synonym option then the object returned | |
466 | is the five-element list | |
467 | for the other option that the synonym refers to. If an error occurs | |
468 | (e.g., because \fInamePtr\fR contains an unknown option name) then NULL | |
469 | is returned and an error message is left in \fIinterp\fR's result unless | |
470 | \fIinterp\fR is NULL. | |
471 | .PP | |
472 | \fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted. | |
473 | It frees all of the resources associated with any of the configuration | |
474 | options defined in \fIrecordPtr\fR by \fIoptionTable\fR. | |
475 | .PP | |
476 | The \fBTk_Offset\fR macro is provided as a safe way of generating the | |
477 | \fIobjOffset\fR and \fIinternalOffset\fR values for entries in | |
478 | Tk_OptionSpec structures. It takes two arguments: the name of a type | |
479 | of record, and the name of a field in that record. It returns the byte | |
480 | offset of the named field in records of the given type. | |
481 | ||
482 | .SH "TEMPLATES" | |
483 | .PP | |
484 | The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR | |
485 | via its \fItemplatePtr\fR argument describes the configuration options | |
486 | supported by a particular class of widgets. Each structure specifies | |
487 | one configuration option and has the following fields: | |
488 | .CS | |
489 | typedef struct { | |
490 | Tk_OptionType \fItype\fR; | |
491 | char *\fIoptionName\fR; | |
492 | char *\fIdbName\fR; | |
493 | char *\fIdbClass\fR; | |
494 | char *\fIdefValue\fR; | |
495 | int \fIobjOffset\fR; | |
496 | int \fIinternalOffset\fR; | |
497 | int \fIflags\fR; | |
498 | ClientData \fIclientData\fR; | |
499 | int \fItypeMask\fR; | |
500 | } Tk_OptionSpec; | |
501 | .CE | |
502 | The \fItype\fR field indicates what kind of configuration option this is | |
503 | (e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for | |
504 | an integer value). \fIType\fR determines how the | |
505 | value of the option is parsed (more on this below). | |
506 | The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR; | |
507 | it is the name used for the option in Tcl commands and passed to | |
508 | procedures via the \fIobjc\fR or \fInamePtr\fR arguments. | |
509 | The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR | |
510 | to look up a default value for this option in the option database; if | |
511 | \fIdbName\fR is NULL then the option database is not used by | |
512 | \fBTk_InitOptions\fR for this option. The \fIdefValue\fR field | |
513 | specifies a default value for this configuration option if no | |
514 | value is specified in the option database. The \fIobjOffset\fR and | |
515 | \fIinternalOffset\fR fields indicate where to store the value of this | |
516 | option in widget records (more on this below); values for the \fIobjOffset\fR | |
517 | and \fIinternalOffset\fR fields should always be generated with the | |
518 | \fBTk_Offset\fR macro. | |
519 | The \fIflags\fR field contains additional information | |
520 | to control the processing of this configuration option (see below | |
521 | for details). | |
522 | \fIClientData\fR provides additional type-specific data needed | |
523 | by certain types. For instance, for TK_OPTION_COLOR types, | |
524 | \fIclientData\fR is a string giving the default value to use on | |
525 | monochrome displays. See the descriptions of the different types | |
526 | below for details. | |
527 | The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to | |
528 | return information about which options were modified; see the description | |
529 | of \fBTk_SetOptions\fR above for details. | |
530 | .PP | |
531 | When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an | |
532 | option into the widget record, they can do it in either of two ways. | |
533 | If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than | |
534 | or equal to zero, then the value of the option is stored as a | |
535 | (Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR. | |
536 | If the \fIinternalOffset\fR field of the Tk_OptionSpec is | |
537 | greater than or equal to zero, then the value of the option is stored | |
538 | in a type-specific internal form at the location in the widget record | |
539 | given by \fIinternalOffset\fR. For example, if the option's type is | |
540 | TK_OPTION_INT then the internal form is an integer. If the | |
541 | \fIobjOffset\fR or \fIinternalOffset\fR field is negative then the | |
542 | value is not stored in that form. At least one of the offsets must be | |
543 | greater than or equal to zero. | |
544 | .PP | |
545 | The \fIflags\fR field consists of one or more bits ORed together. At | |
546 | present only a single flag is supported: TK_OPTION_NULL_OK. If | |
547 | this bit is set for an option then an empty string will be accepted as | |
548 | the value for the option and the resulting internal form will be a | |
549 | NULL pointer, a zero value, or \fBNone\fR, depending on the type of | |
550 | the option. If the flag is not set then empty strings will result | |
551 | in errors. | |
552 | TK_OPTION_NULL_OK is typically used to allow a | |
553 | feature to be turned off entirely, e.g. set a cursor value to | |
554 | \fBNone\fR so that a window simply inherits its parent's cursor. | |
555 | Not all option types support the TK_OPTION_NULL_OK | |
556 | flag; for those that do, there is an explicit indication of that fact | |
557 | in the descriptions below. | |
558 | .PP | |
559 | The \fItype\fR field of each Tk_OptionSpec structure determines | |
560 | how to parse the value of that configuration option. The | |
561 | legal value for \fItype\fR, and the corresponding actions, are | |
562 | described below. If the type requires a \fItkwin\fR value to be | |
563 | passed into procedures like \fBTk_SetOptions\fR, or if it uses | |
564 | the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated | |
565 | explicitly; if not mentioned, the type requires neither \fItkwin\fR | |
566 | nor \fIclientData\fR. | |
567 | .TP | |
568 | \fBTK_OPTION_ANCHOR\fR | |
569 | The value must be a standard anchor position such as \fBne\fR or | |
570 | \fBcenter\fR. The internal form is a Tk_Anchor value like the ones | |
571 | returned by \fBTk_GetAnchorFromObj\fR. | |
572 | .TP | |
573 | \fBTK_OPTION_BITMAP\fR | |
574 | The value must be a standard Tk bitmap name. The internal form is a | |
575 | Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR. | |
576 | This option type requires \fItkwin\fR to be supplied to procedures | |
577 | such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. | |
578 | .TP | |
579 | \fBTK_OPTION_BOOLEAN\fR | |
580 | The value must be a standard boolean value such as \fBtrue\fR or | |
581 | \fBno\fR. The internal form is an integer with value 0 or 1. | |
582 | .TP | |
583 | \fBTK_OPTION_BORDER\fR | |
584 | The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. | |
585 | The internal form is a Tk_3DBorder token like the ones returned | |
586 | by \fBTk_Alloc3DBorderFromObj\fR. | |
587 | This option type requires \fItkwin\fR to be supplied to procedures | |
588 | such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. | |
589 | .TP | |
590 | \fBTK_OPTION_COLOR\fR | |
591 | The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. | |
592 | The internal form is an (XColor *) token like the ones returned by | |
593 | \fBTk_AllocColorFromObj\fR. | |
594 | This option type requires \fItkwin\fR to be supplied to procedures | |
595 | such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. | |
596 | .TP | |
597 | \fBTK_OPTION_CURSOR\fR | |
598 | The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR. | |
599 | The internal form is a Tk_Cursor token like the ones returned by | |
600 | \fBTk_AllocCursorFromObj\fR. | |
601 | This option type requires \fItkwin\fR to be supplied to procedures | |
602 | such as \fBTk_SetOptions\fR, and when the option is set the cursor | |
603 | for the window is changed by calling \fBXDefineCursor\fR. This | |
604 | option type also supports the TK_OPTION_NULL_OK flag. | |
605 | .TP | |
606 | \fBTK_OPTION_CUSTOM\fR | |
607 | This option allows applications to define new option types. The | |
608 | clientData field of the entry points to a structure defining the new | |
609 | option type. See the section CUSTOM OPTION TYPES below for details. | |
610 | .TP | |
611 | \fBTK_OPTION_DOUBLE\fR | |
612 | The string value must be a floating-point number in | |
613 | the format accepted by \fBstrtol\fR. The internal form is a C | |
614 | \fBdouble\fR value. This option type supports the TK_OPTION_NULL_OK | |
615 | flag; if a NULL value is set, the internal representation is set to zero. | |
616 | .TP | |
617 | \fBTK_OPTION_END\fR | |
618 | Marks the end of the template. There must be a Tk_OptionSpec structure | |
619 | with \fItype\fR TK_OPTION_END at the end of each template. If the | |
620 | \fIclientData\fR field of this structure isn't NULL, then it points to | |
621 | an additional array of Tk_OptionSpec's, which is itself terminated by | |
622 | another TK_OPTION_END entry. Templates may be chained arbitrarily | |
623 | deeply. This feature allows common options to be shared by several | |
624 | widget classes. | |
625 | .TP | |
626 | \fBTK_OPTION_FONT\fR | |
627 | The value must be a standard font name such as \fBTimes 16\fR. | |
628 | The internal form is a Tk_Font handle like the ones returned by | |
629 | \fBTk_AllocFontFromObj\fR. | |
630 | This option type requires \fItkwin\fR to be supplied to procedures | |
631 | such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. | |
632 | .TP | |
633 | \fBTK_OPTION_INT\fR | |
634 | The string value must be an integer in the format accepted by | |
635 | \fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to | |
636 | specify octal or hexadecimal numbers, respectively). The internal | |
637 | form is a C \fBint\fR value. | |
638 | .TP | |
639 | \fBTK_OPTION_JUSTIFY\fR | |
640 | The value must be a standard justification value such as \fBleft\fR. | |
641 | The internal form is a Tk_Justify like the values returned by | |
642 | \fBTk_GetJustifyFromObj\fR. | |
643 | .TP | |
644 | \fBTK_OPTION_PIXELS\fR | |
645 | The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR. | |
646 | The internal form is an integer value giving a | |
647 | distance in pixels, like the values returned by | |
648 | \fBTk_GetPixelsFromObj\fR. Note: if the \fIobjOffset\fR field isn't | |
649 | used then information about the original value of this option will be lost. | |
650 | See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. This option | |
651 | type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the | |
652 | internal representation is set to zero. | |
653 | .TP | |
654 | \fBTK_OPTION_RELIEF\fR | |
655 | The value must be standard relief such as \fBraised\fR. | |
656 | The internal form is an integer relief value such as | |
657 | TK_RELIEF_RAISED. This option type supports the TK_OPTION_NULL_OK | |
658 | flag; if the empty string is specified as the value for the option, | |
659 | the integer relief value is set to TK_RELIEF_NULL. | |
660 | .TP | |
661 | \fBTK_OPTION_STRING\fR | |
662 | The value may be any string. The internal form is a (char *) pointer | |
663 | that points to a dynamically allocated copy of the value. | |
664 | This option type supports the TK_OPTION_NULL_OK flag. | |
665 | .TP | |
666 | \fBTK_OPTION_STRING_TABLE\fR | |
667 | For this type, \fIclientData\fR is a pointer to an array of strings | |
668 | suitable for passing to \fBTcl_GetIndexFromObj\fR. The value must | |
669 | be one of the strings in the table, or a unique abbreviation of | |
670 | one of the strings. The internal form is an integer giving the index | |
671 | into the table of the matching string, like the return value | |
672 | from \fBTcl_GetStringFromObj\fR. | |
673 | .TP | |
674 | \fBTK_OPTION_SYNONYM\fR | |
675 | This type is used to provide alternative names for an option (for | |
676 | example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR). | |
677 | The \fBclientData\fR field is a (char *) pointer that gives | |
678 | the name of another option in the same table. Whenever the | |
679 | synonym option is used, the information from the other option | |
680 | will be used instead. | |
681 | .TP | |
682 | \fBTK_OPTION_WINDOW\fR | |
683 | The value must be a window path name. The internal form is a | |
684 | \fBTk_Window\fR token for the window. | |
685 | This option type requires \fItkwin\fR to be supplied to procedures | |
686 | such as \fBTk_SetOptions\fR (in order to identify the application), | |
687 | and it supports the TK_OPTION_NULL_OK flag. | |
688 | ||
689 | .SH "STORAGE MANAGEMENT ISSUES" | |
690 | .PP | |
691 | If a field of a widget record has its offset stored in the \fIobjOffset\fR | |
692 | or \fIinternalOffset\fR field of a Tk_OptionSpec structure then the | |
693 | procedures described here will handle all of the storage allocation and | |
694 | resource management issues associated with the field. When the value | |
695 | of an option is changed, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR) | |
696 | will automatically free any resources associated with the old value, such as | |
697 | Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for | |
698 | TK_OPTION_STRING options. For an option stored as an object using the | |
699 | \fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the | |
700 | object pointed to by the \fIobjv\fR value from the call to | |
701 | \fBTk_SetOptions\fR. The reference count for this object is incremented | |
702 | when a pointer to it is stored in the widget record and decremented when | |
703 | the option is modified. When the widget is deleted | |
704 | \fBTk_FreeConfigOptions\fR should be invoked; it will free the resources | |
705 | associated with all options and decrement reference counts for any | |
706 | objects. | |
707 | .PP | |
708 | However, the widget code is responsible for storing NULL or \fBNone\fR in | |
709 | all pointer and token fields before invoking \fBTk_InitOptions\fR. | |
710 | This is needed to allow proper cleanup in the rare case where | |
711 | an error occurs in \fBTk_InitOptions\fR. | |
712 | ||
713 | .SH "OBJOFFSET VS. INTERNALOFFSET" | |
714 | .PP | |
715 | In most cases it is simplest to use the \fIinternalOffset\fR field of | |
716 | a Tk_OptionSpec structure and not the \fIobjOffset\fR field. This | |
717 | makes the internal form of the value immediately available to the | |
718 | widget code so the value doesn't have to be extracted from an object | |
719 | each time it is used. However, there are two cases where the | |
720 | \fIobjOffset\fR field is useful. The first case is for | |
721 | TK_OPTION_PIXELS options. In this case, the internal form is | |
722 | an integer pixel value that is valid only for a particular screen. | |
723 | If the value of the option is retrieved, it will be returned as a simple | |
724 | number. For example, after the command \fB.b configure \-borderwidth 2m\fR, | |
725 | the command \fB.b configure \-borderwidth\fR might return 7, which is the | |
726 | integer pixel value corresponding to \fB2m\fR. Unfortunately, this loses | |
727 | the original screen-independent value. Thus for TK_OPTION_PIXELS options | |
728 | it is better to use the \fIobjOffset\fR field. In this case the original | |
729 | value of the option is retained in the object and can be returned when | |
730 | the option is retrieved. In most cases it is convenient to use the | |
731 | \fIinternalOffset\fR field field as well, so that the integer value is | |
732 | immediately available for use in the widget code (alternatively, | |
733 | \fBTk_GetPixelsFromObj\fR can be used to extract the integer value from | |
734 | the object whenever it is needed). Note: the problem of losing information | |
735 | on retrievals exists only for TK_OPTION_PIXELS options. | |
736 | .PP | |
737 | The second reason to use the \fIobjOffset\fR field is in order to | |
738 | implement new types of options not supported by these procedures. | |
739 | To implement a new type of option, you can use TK_OPTION_STRING as | |
740 | the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field | |
741 | but not the \fIinternalOffset\fR field. Then, after calling | |
742 | \fBTk_SetOptions\fR, convert the object to internal form yourself. | |
743 | ||
744 | .SH "CUSTOM OPTION TYPES" | |
745 | .PP | |
746 | Applications can extend the built-in configuration types with | |
747 | additional configuration types by writing procedures to parse, print, | |
748 | free, and restore saved copies of the type and creating a structure | |
749 | pointing to those procedures: | |
750 | .CS | |
751 | typedef struct Tk_ObjCustomOption { | |
752 | char *name; | |
753 | Tk_CustomOptionSetProc *\fIsetProc\fR; | |
754 | Tk_CustomOptionGetProc *\fIgetProc\fR; | |
755 | Tk_CustomOptionRestoreProc *\fIrestoreProc\fR; | |
756 | Tk_CustomOptionFreeProc *\fIfreeProc\fR; | |
757 | ClientData \fIclientData\fR; | |
758 | } Tk_ObjCustomOption; | |
759 | ||
760 | typedef int Tk_CustomOptionSetProc( | |
761 | ClientData \fIclientData\fR, | |
762 | Tcl_Interp *\fIinterp\fR, | |
763 | Tk_Window \fItkwin\fR, | |
764 | Tcl_Obj **\fIvaluePtr\fR, | |
765 | char *\fIrecordPtr\fR, | |
766 | int \fIinternalOffset\fR, | |
767 | char *\fIsaveInternalPtr\fR, | |
768 | int \fIflags\fR); | |
769 | ||
770 | typedef Tcl_Obj *Tk_CustomOptionGetProc( | |
771 | ClientData \fIclientData\fR, | |
772 | Tk_Window \fItkwin\fR, | |
773 | char *\fIrecordPtr\fR, | |
774 | int \fIinternalOffset\fR); | |
775 | ||
776 | typedef void Tk_CustomOptionRestoreProc( | |
777 | ClientData \fIclientData\fR, | |
778 | Tk_Window \fItkwin\fR, | |
779 | char *\fIinternalPtr\fR, | |
780 | char *\fIsaveInternalPtr\fR); | |
781 | ||
782 | typedef void Tk_CustomOptionFreeProc( | |
783 | ClientData \fIclientData\fR, | |
784 | Tk_Window \fItkwin\fR, | |
785 | char *\fIinternalPtr\fR); | |
786 | .CE | |
787 | .PP | |
788 | The Tk_ObjCustomOption structure contains six fields: a name | |
789 | for the custom option type; pointers to the four procedures; and a | |
790 | \fIclientData\fR value to be passed to those procedures when they are | |
791 | invoked. The \fIclientData\fR value typically points to a structure | |
792 | containing information that is needed by the procedures when they are | |
793 | parsing and printing options. \fIRestoreProc\fR and \fIfreeProc\fR | |
794 | may be NULL, indicating that no function should be called for those | |
795 | operations. | |
796 | .PP | |
797 | The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to | |
798 | convert a Tcl_Obj into an internal representation and store the | |
799 | resulting value in the widget record. The arguments are: | |
800 | .RS | |
801 | .TP | |
802 | \fIclientData\fR | |
803 | A copy of the \fIclientData\fR field in the Tk_ObjCustomOption | |
804 | structure. | |
805 | .TP | |
806 | \fIinterp\fR | |
807 | A pointer to a Tcl interpreter, used for error reporting. | |
808 | .TP | |
809 | \fITkwin\fR | |
810 | A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR | |
811 | .TP | |
812 | \fIvaluePtr\fR | |
813 | A pointer to a reference to a Tcl_Obj describing the new value for the | |
814 | option; it could have been specified explicitly in the call to | |
815 | \fBTk_SetOptions\fR or it could come from the option database or a | |
816 | default. If the objOffset for the option is non-negative (the option | |
817 | value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj | |
818 | pointer referenced by \fIvaluePtr\fR is the pointer that will be | |
819 | stored at the objOffset for the option. \fISetProc\fR may modify the | |
820 | value if necessary; for example, \fIsetProc\fR may change the value to | |
821 | NULL to support the TK_OPTION_NULL_OK flag. | |
822 | .TP | |
823 | \fIrecordPtr\fR | |
824 | A pointer to the start of the widget record to modify. | |
825 | .TP | |
826 | \fIinternalOffset\fR | |
827 | Offset in bytes from the start of the widget record to the location | |
828 | where the internal representation of the option value is to be placed. | |
829 | .TP | |
830 | \fIsaveInternalPtr\fR | |
831 | A pointer to storage allocated in a Tk_SavedOptions structure for the | |
832 | internal representation of the original option value. Before setting | |
833 | the option to its new value, \fIsetProc\fR should set the value | |
834 | referenced by \fIsaveInternalPtr\fR to the original value of the | |
835 | option in order to support \fBTk_RestoreSavedOptions\fR. | |
836 | .TP | |
837 | \fIflags\fR | |
838 | A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the | |
839 | option | |
840 | .RE | |
841 | .PP | |
842 | \fISetProc\fR returns a standard Tcl result: TCL_OK to indicate successful | |
843 | processing, or TCL_ERROR to indicate a failure of any kind. An error | |
844 | message may be left in the Tcl interpreter given by \fIinterp\fR in | |
845 | the case of an error. | |
846 | .PP | |
847 | The \fIgetProc\fR procedure is invoked by \fBTk_GetOptionValue\fR and | |
848 | \fBTk_GetOptionInfo\fR to retrieve a Tcl_Obj representation of the | |
849 | internal representation of an option. The \fIclientData\fR argument | |
850 | is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption | |
851 | structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to | |
852 | \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIRecordPtr\fR | |
853 | is a pointer to the beginning of the widget record to query. | |
854 | \fIInternalOffset\fR is the offset in bytes from the beginning of the | |
855 | widget record to the location where the internal representation of the | |
856 | option value is stored. \fIGetProc\fR must return a pointer to a | |
857 | Tcl_Obj representing the value of the option. | |
858 | .PP | |
859 | The \fIrestoreProc\fR procedure is invoked by | |
860 | \fBTk_RestoreSavedOptions\fR to restore a previously saved internal | |
861 | representation of a custom option value. The \fIclientData\fR argument | |
862 | is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption | |
863 | structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to | |
864 | \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR | |
865 | is a pointer to the location where internal representation of the | |
866 | option value is stored. | |
867 | \fISaveInternalPtr\fR is a pointer to the saved value. | |
868 | \fIRestoreProc\fR must copy the value from \fIsaveInternalPtr\fR to | |
869 | \fIinternalPtr\fR to restore the value. \fIRestoreProc\fR need not | |
870 | free any memory associated with either \fIinternalPtr\fR or | |
871 | \fIsaveInternalPtr\fR; \fIfreeProc\fR will be invoked to free that | |
872 | memory if necessary. \fIRestoreProc\fR has no return value. | |
873 | .PP | |
874 | The \fIfreeProc\fR procedure is invoked by \fBTk_SetOptions\fR and | |
875 | \fBTk_FreeSavedOptions\fR to free any storage allocated for the | |
876 | internal representation of a custom option. The \fIclientData\fR argument | |
877 | is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption | |
878 | structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to | |
879 | \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR | |
880 | is a pointer to the location where the internal representation of the | |
881 | option value is stored. The \fIfreeProc\fR must free any storage | |
882 | associated with the option. \fIFreeProc\fR has no return value. | |
883 | ||
884 | ||
885 | .SH KEYWORDS | |
886 | anchor, bitmap, boolean, border, color, configuration option, | |
887 | cursor, double, font, integer, justify, | |
888 | pixels, relief, screen distance, synonym |