1Tk_SetOptions(3) Tk Library Procedures Tk_SetOptions(3)
2______________________________________________________________________________
6
8 Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOp‐
9 tions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue,
10 Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset - process configura‐
11 tion options
12
14 #include <tk.h>
15 Tk_OptionTable
17 Tk_CreateOptionTable(interp, templatePtr)
18 Tk_DeleteOptionTable(optionTable)
20 int
22 Tk_InitOptions(interp, recordPtr, optionTable, tkwin)
23 int
25 Tk_SetOptions(interp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr)
26 Tk_FreeSavedOptions(savedPtr)
28 Tk_RestoreSavedOptions(savedPtr)
30 Tcl_Obj *
32 Tk_GetOptionValue(interp, recordPtr, optionTable, namePtr, tkwin)
33 Tcl_Obj *
35 Tk_GetOptionInfo(interp, recordPtr, optionTable, namePtr, tkwin)
36 Tk_FreeConfigOptions(recordPtr, optionTable, tkwin)
38 int
40 Tk_Offset(type, field)
41
43 Tcl_Interp *interp (in) A Tcl interpreter. Most
44 procedures use this only
45 for returning error mes‐
46 sages; if it is NULL then
47 no error messages are re‐
48 turned. For Tk_CreateOp‐
49 tionTable the value cannot
50 be NULL; it gives the in‐
51 terpreter in which the op‐
52 tion table will be used.
53 const Tk_OptionSpec *templatePtr (in) Points to an array of
55 static information that de‐
56 scribes the configuration
57 options that are supported.
58 Used to build a Tk_Op‐
59 tionTable. The information
60 pointed to by this argument
61 must exist for the lifetime
62 of the Tk_OptionTable.
63 Tk_OptionTable optionTable (in) Token for an option table.
65 Must have been returned by
66 a previous call to Tk_Cre‐
67 ateOptionTable.
68 char *recordPtr (in/out) Points to structure in
70 which values of configura‐
71 tion options are stored;
72 fields of this record are
73 modified by procedures such
74 as Tk_SetOptions and read
75 by procedures such as
76 Tk_GetOptionValue.
77 Tk_Window tkwin (in) For options such as TK_OP‐
79 TION_COLOR, this argument
80 indicates the window in
81 which the option will be
82 used. If optionTable uses
83 no window-dependent op‐
84 tions, then a NULL value
85 may be supplied for this
86 argument.
87 int objc (in) Number of values in objv.
89 Tcl_Obj *const *objv (in) Command-line arguments for
91 setting configuring op‐
92 tions.
93 Tk_SavedOptions *savePtr (out) If not NULL, the structure
95 pointed to by this argument
96 is filled in with the old
97 values of any options that
98 were modified and old val‐
99 ues are restored automati‐
100 cally if an error occurs in
101 Tk_SetOptions.
102 int *maskPtr (out) If not NULL, the word
104 pointed to by maskPtr is
105 filled in with the bit-wise
106 OR of the typeMask fields
107 for the options that were
108 modified.
109 Tk_SavedOptions *savedPtr (in/out) Points to a structure pre‐
111 viously filled in by Tk_Se‐
112 tOptions with old values of
113 modified options.
114 Tcl_Obj *namePtr (in) The value of this object is
116 the name of a particular
117 option. If NULL is passed
118 to Tk_GetOptionInfo then
119 information is returned for
120 all options. Must not be
121 NULL when Tk_GetOptionValue
122 is called.
123 type name type (in) The name of the type of a
125 record.
126 field name field (in) The name of a field in
128 records of type type.
129______________________________________________________________________________
130
132 These procedures handle most of the details of parsing configuration
133 options such as those for Tk widgets. Given a description of what op‐
134 tions are supported, these procedures handle all the details of parsing
135 options and storing their values into a C structure associated with the
136 widget or object. The procedures were designed primarily for widgets in
137 Tk, but they can also be used for other kinds of objects that have con‐
138 figuration options. In the rest of this manual page “widget” will be
139 used to refer to the object whose options are being managed; in prac‐
140 tice the object may not actually be a widget. The term “widget record”
141 is used to refer to the C-level structure in which information about a
142 particular widget or object is stored.
143 Note: the easiest way to learn how to use these procedures is to look
145 at a working example. In Tk, the simplest example is the code that im‐
146 plements the button family of widgets, which is in tkButton.c. Other
147 examples are in tkSquare.c and tkMenu.c.
148 In order to use these procedures, the code that implements the widget
150 must contain a static array of Tk_OptionSpec structures. This is a tem‐
151 plate that describes the various options supported by that class of
152 widget; there is a separate template for each kind of widget. The tem‐
153 plate contains information such as the name of each option, its type,
154 its default value, and where the value of the option is stored in the
155 widget record. See TEMPLATES below for more detail.
156 In order to process configuration options efficiently, the static tem‐
158 plate must be augmented with additional information that is available
159 only at runtime. The procedure Tk_CreateOptionTable creates this dy‐
160 namic information from the template and returns a Tk_OptionTable token
161 that describes both the static and dynamic information. All of the
162 other procedures, such as Tk_SetOptions, take a Tk_OptionTable token as
163 argument. Typically, Tk_CreateOptionTable is called the first time
164 that a widget of a particular class is created and the resulting Tk_Op‐
165 tionTable is used in the future for all widgets of that class. A
166 Tk_OptionTable may be used only in a single interpreter, given by the
167 interp argument to Tk_CreateOptionTable. When an option table is no
168 longer needed Tk_DeleteOptionTable should be called to free all of its
169 resources. All of the option tables for a Tcl interpreter are freed
170 automatically if the interpreter is deleted.
171 Tk_InitOptions is invoked when a new widget is created to set the de‐
173 fault values for all of the widget's configuration options that do not
174 have TK_OPTION_DONT_SET_DEFAULT set in their flags field. Tk_InitOp‐
175 tions is passed a token for an option table (optionTable) and a pointer
176 to a widget record (recordPtr), which is the C structure that holds in‐
177 formation about this widget. Tk_InitOptions uses the information in
178 the option table to choose an appropriate default for each option, ex‐
179 cept those having TK_OPTION_DONT_SET_DEFAULT set, then it stores the
180 default value directly into the widget record, overwriting any informa‐
181 tion that was already present in the widget record. Tk_InitOptions
182 normally returns TCL_OK. If an error occurred while setting the de‐
183 fault values (e.g., because a default value was erroneous) then TCL_ER‐
184 ROR is returned and an error message is left in interp's result if in‐
185 terp is not NULL.
186 Tk_SetOptions is invoked to modify configuration options based on in‐
188 formation specified in a Tcl command. The command might be one that
189 creates a new widget, or a command that modifies options on an existing
190 widget. The objc and objv arguments describe the values of the argu‐
191 ments from the Tcl command. Objv must contain an even number of ob‐
192 jects: the first object of each pair gives the name of an option and
193 the second object gives the new value for that option. Tk_SetOptions
194 looks up each name in optionTable, checks that the new value of the op‐
195 tion conforms to the type in optionTable, and stores the value of the
196 option into the widget record given by recordPtr. Tk_SetOptions nor‐
197 mally returns TCL_OK. If an error occurred (such as an unknown option
198 name or an illegal option value) then TCL_ERROR is returned and an er‐
199 ror message is left in interp's result if interp is not NULL.
200 Tk_SetOptions has two additional features. First, if the maskPtr argu‐
202 ment is not NULL then it points to an integer value that is filled in
203 with information about the options that were modified. For each option
204 in the template passed to Tk_CreateOptionTable there is a typeMask
205 field. The bits of this field are defined by the code that implements
206 the widget; for example, each bit might correspond to a particular con‐
207 figuration option. Alternatively, bits might be used functionally.
208 For example, one bit might be used for redisplay: all options that af‐
209 fect the widget's display, such that changing the option requires the
210 widget to be redisplayed, might have that bit set. Another bit might
211 indicate that the geometry of the widget must be recomputed, and so on.
212 Tk_SetOptions OR's together the typeMask fields from all the options
213 that were modified and returns this value at *maskPtr; the caller can
214 then use this information to optimize itself so that, for example, it
215 does not redisplay the widget if the modified options do not affect the
216 widget's appearance.
217 The second additional feature of Tk_SetOptions has to do with error re‐
219 covery. If an error occurs while processing configuration options,
220 this feature makes it possible to restore all the configuration options
221 to their previous values. Errors can occur either while processing op‐
222 tions in Tk_SetOptions or later in the caller. In many cases the
223 caller does additional processing after Tk_SetOptions returns; for ex‐
224 ample, it might use an option value to set a trace on a variable and
225 may detect an error if the variable is an array instead of a scalar.
226 Error recovery is enabled by passing in a non-NULL value for the
227 savePtr argument to Tk_SetOptions; this should be a pointer to an
228 uninitialized Tk_SavedOptions structure on the caller's stack. Tk_Se‐
229 tOptions overwrites the structure pointed to by savePtr with informa‐
230 tion about the old values of any options modified by the procedure. If
231 Tk_SetOptions returns successfully, the caller uses the structure in
232 one of two ways. If the caller completes its processing of the new op‐
233 tions without any errors, then it must pass the structure to
234 Tk_FreeSavedOptions so that the old values can be freed. If the caller
235 detects an error in its processing of the new options, then it should
236 pass the structure to Tk_RestoreSavedOptions, which will copy the old
237 values back into the widget record and free the new values. If Tk_Se‐
238 tOptions detects an error then it automatically restores any options
239 that had already been modified and leaves *savePtr in an empty state:
240 the caller need not call either Tk_FreeSavedOptions or Tk_RestoreSave‐
241 dOptions. If the savePtr argument to Tk_SetOptions is NULL then Tk_Se‐
242 tOptions frees each old option value immediately when it sets a new
243 value for the option. In this case, if an error occurs in the third
244 option, the old values for the first two options cannot be restored.
245 Tk_GetOptionValue returns the current value of a configuration option
247 for a particular widget. The namePtr argument contains the name of an
248 option; Tk_GetOptionValue uses optionTable to lookup the option and ex‐
249 tract its value from the widget record pointed to by recordPtr, then it
250 returns an object containing that value. If an error occurs (e.g., be‐
251 cause namePtr contains an unknown option name) then NULL is returned
252 and an error message is left in interp's result unless interp is NULL.
253 Tk_GetOptionInfo returns information about configuration options in a
255 form suitable for configure widget commands. If the namePtr argument
256 is not NULL, it points to an object that gives the name of a configura‐
257 tion option; Tk_GetOptionInfo returns an object containing a list with
258 five elements, which are the name of the option, the name and class
259 used for the option in the option database, the default value for the
260 option, and the current value for the option. If the namePtr argument
261 is NULL, then Tk_GetOptionInfo returns information about all options in
262 the form of a list of lists; each sublist describes one option. Syn‐
263 onym options are handled differently depending on whether namePtr is
264 NULL: if namePtr is NULL then the sublist for each synonym option has
265 only two elements, which are the name of the option and the name of the
266 other option that it refers to; if namePtr is non-NULL and names a syn‐
267 onym option then the object returned is the five-element list for the
268 other option that the synonym refers to. If an error occurs (e.g., be‐
269 cause namePtr contains an unknown option name) then NULL is returned
270 and an error message is left in interp's result unless interp is NULL.
271 Tk_FreeConfigOptions must be invoked when a widget is deleted. It
273 frees all of the resources associated with any of the configuration op‐
274 tions defined in recordPtr by optionTable.
275 The Tk_Offset macro is provided as a safe way of generating the objOff‐
277 set and internalOffset values for entries in Tk_OptionSpec structures.
278 It takes two arguments: the name of a type of record, and the name of a
279 field in that record. It returns the byte offset of the named field in
280 records of the given type.
281
283 The array of Tk_OptionSpec structures passed to Tk_CreateOptionTable
284 via its templatePtr argument describes the configuration options sup‐
285 ported by a particular class of widgets. Each structure specifies one
286 configuration option and has the following fields:
287 typedef struct {
288 Tk_OptionType type;
289 const char *optionName;
290 const char *dbName;
291 const char *dbClass;
292 const char *defValue;
293 int objOffset;
294 int internalOffset;
295 int flags;
296 const void *clientData;
297 int typeMask;
298 } Tk_OptionSpec;
299 The type field indicates what kind of configuration option this is
300 (e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for an inte‐
301 ger value). Type determines how the value of the option is parsed
302 (more on this below). The optionName field is a string such as -font
303 or -bg; it is the name used for the option in Tcl commands and passed
304 to procedures via the objc or namePtr arguments. The dbName and db‐
305 Class fields are used by Tk_InitOptions to look up a default value for
306 this option in the option database; if dbName is NULL then the option
307 database is not used by Tk_InitOptions for this option. The defValue
308 field specifies a default value for this configuration option if no
309 value is specified in the option database. The objOffset and inter‐
310 nalOffset fields indicate where to store the value of this option in
311 widget records (more on this below); values for the objOffset and in‐
312 ternalOffset fields should always be generated with the Tk_Offset
313 macro. The flags field contains additional information to control the
314 processing of this configuration option (see below for details).
315 ClientData provides additional type-specific data needed by certain
316 types. For instance, for TK_OPTION_COLOR types, clientData is a string
317 giving the default value to use on monochrome displays. See the de‐
318 scriptions of the different types below for details. The last field,
319 typeMask, is used by Tk_SetOptions to return information about which
320 options were modified; see the description of Tk_SetOptions above for
321 details.
322 When Tk_InitOptions and Tk_SetOptions store the value of an option into
324 the widget record, they can do it in either of two ways. If the ob‐
325 jOffset field of the Tk_OptionSpec is greater than or equal to zero,
326 then the value of the option is stored as a (Tcl_Obj *) at the location
327 in the widget record given by objOffset. If the internalOffset field
328 of the Tk_OptionSpec is greater than or equal to zero, then the value
329 of the option is stored in a type-specific internal form at the loca‐
330 tion in the widget record given by internalOffset. For example, if the
331 option's type is TK_OPTION_INT then the internal form is an integer.
332 If the objOffset or internalOffset field is negative then the value is
333 not stored in that form. At least one of the offsets must be greater
334 than or equal to zero.
335 The flags field consists of one or more bits ORed together. The follow‐
337 ing flags are supported:
338 TK_OPTION_NULL_OK
340 If this bit is set for an option then an empty string will be
341 accepted as the value for the option and the resulting internal
342 form will be a NULL pointer, a zero value, or None, depending on
343 the type of the option. If the flag is not set then empty
344 strings will result in errors. TK_OPTION_NULL_OK is typically
345 used to allow a feature to be turned off entirely, e.g. set a
346 cursor value to None so that a window simply inherits its par‐
347 ent's cursor. Not all option types support the TK_OP‐
348 TION_NULL_OK flag; for those that do, there is an explicit indi‐
349 cation of that fact in the descriptions below.
350 TK_OPTION_DONT_SET_DEFAULT
352 If this bit is set for an option then no default value will be
353 set in Tk_InitOptions for this option. Neither the option data‐
354 base, nor any system default value, nor optionTable are used to
355 give a default value to this option. Instead it is assumed that
356 the caller has already supplied a default value in the widget
357 code.
358 The type field of each Tk_OptionSpec structure determines how to parse
360 the value of that configuration option. The legal value for type, and
361 the corresponding actions, are described below. If the type requires a
362 tkwin value to be passed into procedures like Tk_SetOptions, or if it
363 uses the clientData field of the Tk_OptionSpec, then it is indicated
364 explicitly; if not mentioned, the type requires neither tkwin nor
365 clientData.
366 TK_OPTION_ANCHOR
368 The value must be a standard anchor position such as ne or cen‐
369 ter. The internal form is a Tk_Anchor value like the ones re‐
370 turned by Tk_GetAnchorFromObj.
371 TK_OPTION_BITMAP
373 The value must be a standard Tk bitmap name. The internal form
374 is a Pixmap token like the ones returned by Tk_AllocBitmapFro‐
375 mObj. This option type requires tkwin to be supplied to proce‐
376 dures such as Tk_SetOptions, and it supports the TK_OP‐
377 TION_NULL_OK flag.
378 TK_OPTION_BOOLEAN
380 The value must be a standard boolean value such as true or no.
381 The internal form is an integer with value 0 or 1.
382 TK_OPTION_BORDER
384 The value must be a standard color name such as red or #ff8080.
385 The internal form is a Tk_3DBorder token like the ones returned
386 by Tk_Alloc3DBorderFromObj. This option type requires tkwin to
387 be supplied to procedures such as Tk_SetOptions, and it supports
388 the TK_OPTION_NULL_OK flag.
389 TK_OPTION_COLOR
391 The value must be a standard color name such as red or #ff8080.
392 The internal form is an (XColor *) token like the ones returned
393 by Tk_AllocColorFromObj. This option type requires tkwin to be
394 supplied to procedures such as Tk_SetOptions, and it supports
395 the TK_OPTION_NULL_OK flag.
396 TK_OPTION_CURSOR
398 The value must be a standard cursor name such as cross or @foo.
399 The internal form is a Tk_Cursor token like the ones returned by
400 Tk_AllocCursorFromObj. This option type requires tkwin to be
401 supplied to procedures such as Tk_SetOptions, and when the op‐
402 tion is set the cursor for the window is changed by calling XDe‐
403 fineCursor. This option type also supports the TK_OP‐
404 TION_NULL_OK flag.
405 TK_OPTION_CUSTOM
407 This option allows applications to define new option types. The
408 clientData field of the entry points to a structure defining the
409 new option type. See the section CUSTOM OPTION TYPES below for
410 details.
411 TK_OPTION_DOUBLE
413 The string value must be a floating-point number in the format
414 accepted by strtol. The internal form is a C double value.
415 This option type supports the TK_OPTION_NULL_OK flag; if a NULL
416 value is set, the internal representation is set to zero.
417 TK_OPTION_END
419 Marks the end of the template. There must be a Tk_OptionSpec
420 structure with type TK_OPTION_END at the end of each template.
421 If the clientData field of this structure is not NULL, then it
422 points to an additional array of Tk_OptionSpec's, which is it‐
423 self terminated by another TK_OPTION_END entry. Templates may
424 be chained arbitrarily deeply. This feature allows common op‐
425 tions to be shared by several widget classes.
426 TK_OPTION_FONT
428 The value must be a standard font name such as Times 16. The
429 internal form is a Tk_Font handle like the ones returned by
430 Tk_AllocFontFromObj. This option type requires tkwin to be sup‐
431 plied to procedures such as Tk_SetOptions, and it supports the
432 TK_OPTION_NULL_OK flag.
433 TK_OPTION_INT
435 The string value must be an integer in the format accepted by
436 strtol (e.g. 0 and 0x prefixes may be used to specify octal or
437 hexadecimal numbers, respectively). The internal form is a C
438 int value.
439 TK_OPTION_JUSTIFY
441 The value must be a standard justification value such as left.
442 The internal form is a Tk_Justify like the values returned by
443 Tk_GetJustifyFromObj.
444 TK_OPTION_PIXELS
446 The value must specify a screen distance such as 2i or 6.4. The
447 internal form is an integer value giving a distance in pixels,
448 like the values returned by Tk_GetPixelsFromObj. Note: if the
449 objOffset field is not used then information about the original
450 value of this option will be lost. See OBJOFFSET VS. INTER‐
451 NALOFFSET below for details. This option type supports the
452 TK_OPTION_NULL_OK flag; if a NULL value is set, the internal
453 representation is set to zero.
454 TK_OPTION_RELIEF
456 The value must be standard relief such as raised. The internal
457 form is an integer relief value such as TK_RELIEF_RAISED. This
458 option type supports the TK_OPTION_NULL_OK flag; if the empty
459 string is specified as the value for the option, the integer re‐
460 lief value is set to TK_RELIEF_NULL.
461 TK_OPTION_STRING
463 The value may be any string. The internal form is a (char *)
464 pointer that points to a dynamically allocated copy of the
465 value. This option type supports the TK_OPTION_NULL_OK flag.
466 TK_OPTION_STRING_TABLE
468 For this type, clientData is a pointer to an array of strings
469 suitable for passing to Tcl_GetIndexFromObj. The value must be
470 one of the strings in the table, or a unique abbreviation of one
471 of the strings. The internal form is an integer giving the in‐
472 dex into the table of the matching string, like the return value
473 from Tcl_GetStringFromObj. This option type supports the TK_OP‐
474 TION_NULL_OK flag; if a NULL value is set, the internal repre‐
475 sentation is set to -1.
476 TK_OPTION_SYNONYM
478 This type is used to provide alternative names for an option
479 (for example, -bg is often used as a synonym for -background).
480 The clientData field is a string that gives the name of another
481 option in the same table. Whenever the synonym option is used,
482 the information from the other option will be used instead.
483 TK_OPTION_WINDOW
485 The value must be a window path name. The internal form is a
486 Tk_Window token for the window. This option type requires tkwin
487 to be supplied to procedures such as Tk_SetOptions (in order to
488 identify the application), and it supports the TK_OPTION_NULL_OK
489 flag.
490
492 If a field of a widget record has its offset stored in the objOffset or
493 internalOffset field of a Tk_OptionSpec structure then the procedures
494 described here will handle all of the storage allocation and resource
495 management issues associated with the field. When the value of an op‐
496 tion is changed, Tk_SetOptions (or Tk_FreeSavedOptions) will automati‐
497 cally free any resources associated with the old value, such as
498 Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for
499 TK_OPTION_STRING options. For an option stored as an object using the
500 objOffset field of a Tk_OptionSpec, the widget record shares the object
501 pointed to by the objv value from the call to Tk_SetOptions. The ref‐
502 erence count for this object is incremented when a pointer to it is
503 stored in the widget record and decremented when the option is modi‐
504 fied. When the widget is deleted Tk_FreeConfigOptions should be in‐
505 voked; it will free the resources associated with all options and
506 decrement reference counts for any objects.
507 However, the widget code is responsible for storing NULL or None in all
509 pointer and token fields before invoking Tk_InitOptions. This is
510 needed to allow proper cleanup in the rare case where an error occurs
511 in Tk_InitOptions.
512
514 In most cases it is simplest to use the internalOffset field of a
515 Tk_OptionSpec structure and not the objOffset field. This makes the
516 internal form of the value immediately available to the widget code so
517 the value does not have to be extracted from an object each time it is
518 used. However, there are two cases where the objOffset field is use‐
519 ful. The first case is for TK_OPTION_PIXELS options. In this case,
520 the internal form is an integer pixel value that is valid only for a
521 particular screen. If the value of the option is retrieved, it will be
522 returned as a simple number. For example, after the command .b config‐
523 ure -borderwidth 2m, the command .b configure -borderwidth might return
524 7, which is the integer pixel value corresponding to 2m. Unfortu‐
525 nately, this loses the original screen-independent value. Thus for
526 TK_OPTION_PIXELS options it is better to use the objOffset field. In
527 this case the original value of the option is retained in the object
528 and can be returned when the option is retrieved. In most cases it is
529 convenient to use the internalOffset field as well, so that the integer
530 value is immediately available for use in the widget code (alterna‐
531 tively, Tk_GetPixelsFromObj can be used to extract the integer value
532 from the object whenever it is needed). Note: the problem of losing
533 information on retrievals exists only for TK_OPTION_PIXELS options.
534 The second reason to use the objOffset field is in order to implement
536 new types of options not supported by these procedures. To implement a
537 new type of option, you can use TK_OPTION_STRING as the type in the
538 Tk_OptionSpec structure and set the objOffset field but not the inter‐
539 nalOffset field. Then, after calling Tk_SetOptions, convert the object
540 to internal form yourself.
541
543 Applications can extend the built-in configuration types with addi‐
544 tional configuration types by writing procedures to parse, print, free,
545 and restore saved copies of the type and creating a structure pointing
546 to those procedures:
547 typedef struct Tk_ObjCustomOption {
548 char *name;
549 Tk_CustomOptionSetProc *setProc;
550 Tk_CustomOptionGetProc *getProc;
551 Tk_CustomOptionRestoreProc *restoreProc;
552 Tk_CustomOptionFreeProc *freeProc;
553 ClientData clientData;
554 } Tk_ObjCustomOption;
555 typedef int Tk_CustomOptionSetProc(
557 ClientData clientData,
558 Tcl_Interp *interp,
559 Tk_Window tkwin,
560 Tcl_Obj **valuePtr,
561 char *recordPtr,
562 int internalOffset,
563 char *saveInternalPtr,
564 int flags);
565 typedef Tcl_Obj *Tk_CustomOptionGetProc(
567 ClientData clientData,
568 Tk_Window tkwin,
569 char *recordPtr,
570 int internalOffset);
571 typedef void Tk_CustomOptionRestoreProc(
573 ClientData clientData,
574 Tk_Window tkwin,
575 char *internalPtr,
576 char *saveInternalPtr);
577 typedef void Tk_CustomOptionFreeProc(
579 ClientData clientData,
580 Tk_Window tkwin,
581 char *internalPtr);
582 The Tk_ObjCustomOption structure contains six fields: a name for the
584 custom option type; pointers to the four procedures; and a clientData
585 value to be passed to those procedures when they are invoked. The
586 clientData value typically points to a structure containing information
587 that is needed by the procedures when they are parsing and printing op‐
588 tions. RestoreProc and freeProc may be NULL, indicating that no func‐
589 tion should be called for those operations.
590 The setProc procedure is invoked by Tk_SetOptions to convert a Tcl_Obj
592 into an internal representation and store the resulting value in the
593 widget record. The arguments are:
594 clientData
596 A copy of the clientData field in the Tk_ObjCustomOption
597 structure.
598 interp A pointer to a Tcl interpreter, used for error reporting.
600 Tkwin A copy of the tkwin argument to Tk_SetOptions
602 valuePtr
604 A pointer to a reference to a Tcl_Obj describing the new
605 value for the option; it could have been specified ex‐
606 plicitly in the call to Tk_SetOptions or it could come
607 from the option database or a default. If the objOffset
608 for the option is non-negative (the option value is
609 stored as a (Tcl_Obj *) in the widget record), the
610 Tcl_Obj pointer referenced by valuePtr is the pointer
611 that will be stored at the objOffset for the option.
612 SetProc may modify the value if necessary; for example,
613 setProc may change the value to NULL to support the
614 TK_OPTION_NULL_OK flag.
615 recordPtr
617 A pointer to the start of the widget record to modify.
618 internalOffset
620 Offset in bytes from the start of the widget record to
621 the location where the internal representation of the op‐
622 tion value is to be placed.
623 saveInternalPtr
625 A pointer to storage allocated in a Tk_SavedOptions
626 structure for the internal representation of the original
627 option value. Before setting the option to its new
628 value, setProc should set the value referenced by saveIn‐
629 ternalPtr to the original value of the option in order to
630 support Tk_RestoreSavedOptions.
631 flags A copy of the flags field in the Tk_OptionSpec structure
633 for the option
634 SetProc returns a standard Tcl result: TCL_OK to indicate successful
636 processing, or TCL_ERROR to indicate a failure of any kind. An error
637 message may be left in the Tcl interpreter given by interp in the case
638 of an error.
639 The getProc procedure is invoked by Tk_GetOptionValue and Tk_GetOption‐
641 Info to retrieve a Tcl_Obj representation of the internal representa‐
642 tion of an option. The clientData argument is a copy of the clientData
643 field in the Tk_ObjCustomOption structure. Tkwin is a copy of the tk‐
644 win argument to Tk_GetOptionValue or Tk_GetOptionInfo. RecordPtr is a
645 pointer to the beginning of the widget record to query. InternalOffset
646 is the offset in bytes from the beginning of the widget record to the
647 location where the internal representation of the option value is
648 stored. GetProc must return a pointer to a Tcl_Obj representing the
649 value of the option.
650 The restoreProc procedure is invoked by Tk_RestoreSavedOptions to re‐
652 store a previously saved internal representation of a custom option
653 value. The clientData argument is a copy of the clientData field in
654 the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argu‐
655 ment to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr is a
656 pointer to the location where internal representation of the option
657 value is stored. SaveInternalPtr is a pointer to the saved value. Re‐
658 storeProc must copy the value from saveInternalPtr to internalPtr to
659 restore the value. RestoreProc need not free any memory associated
660 with either internalPtr or saveInternalPtr; freeProc will be invoked to
661 free that memory if necessary. RestoreProc has no return value.
662 The freeProc procedure is invoked by Tk_SetOptions and Tk_FreeSavedOp‐
664 tions to free any storage allocated for the internal representation of
665 a custom option. The clientData argument is a copy of the clientData
666 field in the Tk_ObjCustomOption structure. Tkwin is a copy of the tk‐
667 win argument to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr is
668 a pointer to the location where the internal representation of the op‐
669 tion value is stored. The freeProc must free any storage associated
670 with the option. FreeProc has no return value.
671
673 anchor, bitmap, boolean, border, color, configuration option, cursor,
674 double, font, integer, justify, pixels, relief, screen distance, syn‐
675 onym
676Tk 8.1 Tk_SetOptions(3)