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
48 returned. For Tk_CreateOp‐
49 tionTable the value cannot
50 be NULL; it gives the
51 interpreter in which the
52 option table will be used.
53 const Tk_OptionSpec *templatePtr (in) Points to an array of
55 static information that
56 describes the configuration
57 options that are supported.
58 Used to build a
59 Tk_OptionTable. The infor‐
60 mation pointed to by this
61 argument must exist for the
62 lifetime of the
63 Tk_OptionTable.
64 Tk_OptionTable optionTable (in) Token for an option table.
66 Must have been returned by
67 a previous call to Tk_Cre‐
68 ateOptionTable.
69 char *recordPtr (in/out) Points to structure in
71 which values of configura‐
72 tion options are stored;
73 fields of this record are
74 modified by procedures such
75 as Tk_SetOptions and read
76 by procedures such as
77 Tk_GetOptionValue.
78 Tk_Window tkwin (in) For options such as
80 TK_OPTION_COLOR, this argu‐
81 ment indicates the window
82 in which the option will be
83 used. If optionTable uses
84 no window-dependent
85 options, then a NULL value
86 may be supplied for this
87 argument.
88 int objc (in) Number of values in objv.
90 Tcl_Obj *const objv[] (in) Command-line arguments for
92 setting configuring
93 options.
94 Tk_SavedOptions *savePtr (out) If not NULL, the structure
96 pointed to by this argument
97 is filled in with the old
98 values of any options that
99 were modified and old val‐
100 ues are restored automati‐
101 cally if an error occurs in
102 Tk_SetOptions.
103 int *maskPtr (out) If not NULL, the word
105 pointed to by maskPtr is
106 filled in with the bit-wise
107 OR of the typeMask fields
108 for the options that were
109 modified.
110 Tk_SavedOptions *savedPtr (in/out) Points to a structure pre‐
112 viously filled in by
113 Tk_SetOptions with old val‐
114 ues of modified options.
115 Tcl_Obj *namePtr (in) The value of this object is
117 the name of a particular
118 option. If NULL is passed
119 to Tk_GetOptionInfo then
120 information is returned for
121 all options. Must not be
122 NULL when Tk_GetOptionValue
123 is called.
124 type name type (in) The name of the type of a
126 record.
127 field name field (in) The name of a field in
129 records of type type.
130______________________________________________________________________________
131
133 These procedures handle most of the details of parsing configuration
134 options such as those for Tk widgets. Given a description of what
135 options are supported, these procedures handle all the details of pars‐
136 ing options and storing their values into a C structure associated with
137 the widget or object. The procedures were designed primarily for wid‐
138 gets in Tk, but they can also be used for other kinds of objects that
139 have configuration options. In the rest of this manual page “widget”
140 will be used to refer to the object whose options are being managed; in
141 practice the object may not actually be a widget. The term “widget
142 record” is used to refer to the C-level structure in which information
143 about a particular widget or object is stored.
144 Note: the easiest way to learn how to use these procedures is to look
146 at a working example. In Tk, the simplest example is the code that
147 implements the button family of widgets, which is in tkButton.c. Other
148 examples are in tkSquare.c and tkMenu.c.
149 In order to use these procedures, the code that implements the widget
151 must contain a static array of Tk_OptionSpec structures. This is a tem‐
152 plate that describes the various options supported by that class of
153 widget; there is a separate template for each kind of widget. The tem‐
154 plate contains information such as the name of each option, its type,
155 its default value, and where the value of the option is stored in the
156 widget record. See TEMPLATES below for more detail.
157 In order to process configuration options efficiently, the static tem‐
159 plate must be augmented with additional information that is available
160 only at runtime. The procedure Tk_CreateOptionTable creates this
161 dynamic information from the template and returns a Tk_OptionTable
162 token that describes both the static and dynamic information. All of
163 the other procedures, such as Tk_SetOptions, take a Tk_OptionTable
164 token as argument. Typically, Tk_CreateOptionTable is called the first
165 time that a widget of a particular class is created and the resulting
166 Tk_OptionTable is used in the future for all widgets of that class. A
167 Tk_OptionTable may be used only in a single interpreter, given by the
168 interp argument to Tk_CreateOptionTable. When an option table is no
169 longer needed Tk_DeleteOptionTable should be called to free all of its
170 resources. All of the option tables for a Tcl interpreter are freed
171 automatically if the interpreter is deleted.
172 Tk_InitOptions is invoked when a new widget is created to set the
174 default values for all of the widget's configuration options that do
175 not have TK_OPTION_DONT_SET_DEFAULT set in their flags field. Tk_Ini‐
176 tOptions is passed a token for an option table (optionTable) and a
177 pointer to a widget record (recordPtr), which is the C structure that
178 holds information about this widget. Tk_InitOptions uses the informa‐
179 tion in the option table to choose an appropriate default for each
180 option, except those having TK_OPTION_DONT_SET_DEFAULT set, then it
181 stores the default value directly into the widget record, overwriting
182 any information that was already present in the widget record. Tk_Ini‐
183 tOptions normally returns TCL_OK. If an error occurred while setting
184 the default values (e.g., because a default value was erroneous) then
185 TCL_ERROR is returned and an error message is left in interp's result
186 if interp is not NULL.
187 Tk_SetOptions is invoked to modify configuration options based on
189 information specified in a Tcl command. The command might be one that
190 creates a new widget, or a command that modifies options on an existing
191 widget. The objc and objv arguments describe the values of the argu‐
192 ments from the Tcl command. Objv must contain an even number of
193 objects: the first object of each pair gives the name of an option and
194 the second object gives the new value for that option. Tk_SetOptions
195 looks up each name in optionTable, checks that the new value of the
196 option conforms to the type in optionTable, and stores the value of the
197 option into the widget record given by recordPtr. Tk_SetOptions nor‐
198 mally returns TCL_OK. If an error occurred (such as an unknown option
199 name or an illegal option value) then TCL_ERROR is returned and an
200 error message is left in interp's result if interp is not NULL.
201 Tk_SetOptions has two additional features. First, if the maskPtr argu‐
203 ment is not NULL then it points to an integer value that is filled in
204 with information about the options that were modified. For each option
205 in the template passed to Tk_CreateOptionTable there is a typeMask
206 field. The bits of this field are defined by the code that implements
207 the widget; for example, each bit might correspond to a particular con‐
208 figuration option. Alternatively, bits might be used functionally.
209 For example, one bit might be used for redisplay: all options that
210 affect the widget's display, such that changing the option requires the
211 widget to be redisplayed, might have that bit set. Another bit might
212 indicate that the geometry of the widget must be recomputed, and so on.
213 Tk_SetOptions OR's together the typeMask fields from all the options
214 that were modified and returns this value at *maskPtr; the caller can
215 then use this information to optimize itself so that, for example, it
216 does not redisplay the widget if the modified options do not affect the
217 widget's appearance.
218 The second additional feature of Tk_SetOptions has to do with error
220 recovery. If an error occurs while processing configuration options,
221 this feature makes it possible to restore all the configuration options
222 to their previous values. Errors can occur either while processing
223 options in Tk_SetOptions or later in the caller. In many cases the
224 caller does additional processing after Tk_SetOptions returns; for
225 example, it might use an option value to set a trace on a variable and
226 may detect an error if the variable is an array instead of a scalar.
227 Error recovery is enabled by passing in a non-NULL value for the
228 savePtr argument to Tk_SetOptions; this should be a pointer to an
229 uninitialized Tk_SavedOptions structure on the caller's stack.
230 Tk_SetOptions overwrites the structure pointed to by savePtr with
231 information about the old values of any options modified by the proce‐
232 dure. If Tk_SetOptions returns successfully, the caller uses the
233 structure in one of two ways. If the caller completes its processing
234 of the new options without any errors, then it must pass the structure
235 to Tk_FreeSavedOptions so that the old values can be freed. If the
236 caller detects an error in its processing of the new options, then it
237 should pass the structure to Tk_RestoreSavedOptions, which will copy
238 the old values back into the widget record and free the new values. If
239 Tk_SetOptions detects an error then it automatically restores any
240 options that had already been modified and leaves *savePtr in an empty
241 state: the caller need not call either Tk_FreeSavedOptions or
242 Tk_RestoreSavedOptions. If the savePtr argument to Tk_SetOptions is
243 NULL then Tk_SetOptions frees each old option value immediately when it
244 sets a new value for the option. In this case, if an error occurs in
245 the third option, the old values for the first two options cannot be
246 restored.
247 Tk_GetOptionValue returns the current value of a configuration option
249 for a particular widget. The namePtr argument contains the name of an
250 option; Tk_GetOptionValue uses optionTable to lookup the option and
251 extract its value from the widget record pointed to by recordPtr, then
252 it returns an object containing that value. If an error occurs (e.g.,
253 because namePtr contains an unknown option name) then NULL is returned
254 and an error message is left in interp's result unless interp is NULL.
255 Tk_GetOptionInfo returns information about configuration options in a
257 form suitable for configure widget commands. If the namePtr argument
258 is not NULL, it points to an object that gives the name of a configura‐
259 tion option; Tk_GetOptionInfo returns an object containing a list with
260 five elements, which are the name of the option, the name and class
261 used for the option in the option database, the default value for the
262 option, and the current value for the option. If the namePtr argument
263 is NULL, then Tk_GetOptionInfo returns information about all options in
264 the form of a list of lists; each sublist describes one option. Syn‐
265 onym options are handled differently depending on whether namePtr is
266 NULL: if namePtr is NULL then the sublist for each synonym option has
267 only two elements, which are the name of the option and the name of the
268 other option that it refers to; if namePtr is non-NULL and names a syn‐
269 onym option then the object returned is the five-element list for the
270 other option that the synonym refers to. If an error occurs (e.g.,
271 because namePtr contains an unknown option name) then NULL is returned
272 and an error message is left in interp's result unless interp is NULL.
273 Tk_FreeConfigOptions must be invoked when a widget is deleted. It
275 frees all of the resources associated with any of the configuration
276 options defined in recordPtr by optionTable.
277 The Tk_Offset macro is provided as a safe way of generating the objOff‐
279 set and internalOffset values for entries in Tk_OptionSpec structures.
280 It takes two arguments: the name of a type of record, and the name of a
281 field in that record. It returns the byte offset of the named field in
282 records of the given type.
283
285 The array of Tk_OptionSpec structures passed to Tk_CreateOptionTable
286 via its templatePtr argument describes the configuration options sup‐
287 ported by a particular class of widgets. Each structure specifies one
288 configuration option and has the following fields:
289 typedef struct {
290 Tk_OptionType type;
291 const char *optionName;
292 const char *dbName;
293 const char *dbClass;
294 const char *defValue;
295 int objOffset;
296 int internalOffset;
297 int flags;
298 const void *clientData;
299 int typeMask;
300 } Tk_OptionSpec;
301 The type field indicates what kind of configuration option this is
302 (e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for an inte‐
303 ger value). Type determines how the value of the option is parsed
304 (more on this below). The optionName field is a string such as -font
305 or -bg; it is the name used for the option in Tcl commands and passed
306 to procedures via the objc or namePtr arguments. The dbName and
307 dbClass fields are used by Tk_InitOptions to look up a default value
308 for this option in the option database; if dbName is NULL then the
309 option database is not used by Tk_InitOptions for this option. The
310 defValue field specifies a default value for this configuration option
311 if no value is specified in the option database. The objOffset and
312 internalOffset fields indicate where to store the value of this option
313 in widget records (more on this below); values for the objOffset and
314 internalOffset fields should always be generated with the Tk_Offset
315 macro. The flags field contains additional information to control the
316 processing of this configuration option (see below for details).
317 ClientData provides additional type-specific data needed by certain
318 types. For instance, for TK_OPTION_COLOR types, clientData is a string
319 giving the default value to use on monochrome displays. See the
320 descriptions of the different types below for details. The last field,
321 typeMask, is used by Tk_SetOptions to return information about which
322 options were modified; see the description of Tk_SetOptions above for
323 details.
324 When Tk_InitOptions and Tk_SetOptions store the value of an option into
326 the widget record, they can do it in either of two ways. If the
327 objOffset field of the Tk_OptionSpec is greater than or equal to zero,
328 then the value of the option is stored as a (Tcl_Obj *) at the location
329 in the widget record given by objOffset. If the internalOffset field
330 of the Tk_OptionSpec is greater than or equal to zero, then the value
331 of the option is stored in a type-specific internal form at the loca‐
332 tion in the widget record given by internalOffset. For example, if the
333 option's type is TK_OPTION_INT then the internal form is an integer.
334 If the objOffset or internalOffset field is negative then the value is
335 not stored in that form. At least one of the offsets must be greater
336 than or equal to zero.
337 The flags field consists of one or more bits ORed together. The follow‐
339 ing flags are supported:
340 TK_OPTION_NULL_OK
342 If this bit is set for an option then an empty string will be
343 accepted as the value for the option and the resulting internal
344 form will be a NULL pointer, a zero value, or None, depending on
345 the type of the option. If the flag is not set then empty
346 strings will result in errors. TK_OPTION_NULL_OK is typically
347 used to allow a feature to be turned off entirely, e.g. set a
348 cursor value to None so that a window simply inherits its par‐
349 ent's cursor. Not all option types support the
350 TK_OPTION_NULL_OK flag; for those that do, there is an explicit
351 indication of that fact in the descriptions below.
352 TK_OPTION_DONT_SET_DEFAULT
354 If this bit is set for an option then no default value will be
355 set in Tk_InitOptions for this option. Neither the option data‐
356 base, nor any system default value, nor optionTable are used to
357 give a default value to this option. Instead it is assumed that
358 the caller has already supplied a default value in the widget
359 code.
360 The type field of each Tk_OptionSpec structure determines how to parse
362 the value of that configuration option. The legal value for type, and
363 the corresponding actions, are described below. If the type requires a
364 tkwin value to be passed into procedures like Tk_SetOptions, or if it
365 uses the clientData field of the Tk_OptionSpec, then it is indicated
366 explicitly; if not mentioned, the type requires neither tkwin nor
367 clientData.
368 TK_OPTION_ANCHOR
370 The value must be a standard anchor position such as ne or cen‐
371 ter. The internal form is a Tk_Anchor value like the ones
372 returned by Tk_GetAnchorFromObj.
373 TK_OPTION_BITMAP
375 The value must be a standard Tk bitmap name. The internal form
376 is a Pixmap token like the ones returned by Tk_AllocBitmapFro‐
377 mObj. This option type requires tkwin to be supplied to proce‐
378 dures such as Tk_SetOptions, and it supports the
379 TK_OPTION_NULL_OK flag.
380 TK_OPTION_BOOLEAN
382 The value must be a standard boolean value such as true or no.
383 The internal form is an integer with value 0 or 1.
384 TK_OPTION_BORDER
386 The value must be a standard color name such as red or #ff8080.
387 The internal form is a Tk_3DBorder token like the ones returned
388 by Tk_Alloc3DBorderFromObj. This option type requires tkwin to
389 be supplied to procedures such as Tk_SetOptions, and it supports
390 the TK_OPTION_NULL_OK flag.
391 TK_OPTION_COLOR
393 The value must be a standard color name such as red or #ff8080.
394 The internal form is an (XColor *) token like the ones returned
395 by Tk_AllocColorFromObj. This option type requires tkwin to be
396 supplied to procedures such as Tk_SetOptions, and it supports
397 the TK_OPTION_NULL_OK flag.
398 TK_OPTION_CURSOR
400 The value must be a standard cursor name such as cross or @foo.
401 The internal form is a Tk_Cursor token like the ones returned by
402 Tk_AllocCursorFromObj. This option type requires tkwin to be
403 supplied to procedures such as Tk_SetOptions, and when the
404 option is set the cursor for the window is changed by calling
405 XDefineCursor. This option type also supports the
406 TK_OPTION_NULL_OK flag.
407 TK_OPTION_CUSTOM
409 This option allows applications to define new option types. The
410 clientData field of the entry points to a structure defining the
411 new option type. See the section CUSTOM OPTION TYPES below for
412 details.
413 TK_OPTION_DOUBLE
415 The string value must be a floating-point number in the format
416 accepted by strtol. The internal form is a C double value.
417 This option type supports the TK_OPTION_NULL_OK flag; if a NULL
418 value is set, the internal representation is set to zero.
419 TK_OPTION_END
421 Marks the end of the template. There must be a Tk_OptionSpec
422 structure with type TK_OPTION_END at the end of each template.
423 If the clientData field of this structure is not NULL, then it
424 points to an additional array of Tk_OptionSpec's, which is
425 itself terminated by another TK_OPTION_END entry. Templates may
426 be chained arbitrarily deeply. This feature allows common
427 options to be shared by several widget classes.
428 TK_OPTION_FONT
430 The value must be a standard font name such as Times 16. The
431 internal form is a Tk_Font handle like the ones returned by
432 Tk_AllocFontFromObj. This option type requires tkwin to be sup‐
433 plied to procedures such as Tk_SetOptions, and it supports the
434 TK_OPTION_NULL_OK flag.
435 TK_OPTION_INT
437 The string value must be an integer in the format accepted by
438 strtol (e.g. 0 and 0x prefixes may be used to specify octal or
439 hexadecimal numbers, respectively). The internal form is a C
440 int value.
441 TK_OPTION_JUSTIFY
443 The value must be a standard justification value such as left.
444 The internal form is a Tk_Justify like the values returned by
445 Tk_GetJustifyFromObj.
446 TK_OPTION_PIXELS
448 The value must specify a screen distance such as 2i or 6.4. The
449 internal form is an integer value giving a distance in pixels,
450 like the values returned by Tk_GetPixelsFromObj. Note: if the
451 objOffset field is not used then information about the original
452 value of this option will be lost. See OBJOFFSET VS. INTER‐
453 NALOFFSET below for details. This option type supports the
454 TK_OPTION_NULL_OK flag; if a NULL value is set, the internal
455 representation is set to zero.
456 TK_OPTION_RELIEF
458 The value must be standard relief such as raised. The internal
459 form is an integer relief value such as TK_RELIEF_RAISED. This
460 option type supports the TK_OPTION_NULL_OK flag; if the empty
461 string is specified as the value for the option, the integer
462 relief value is set to TK_RELIEF_NULL.
463 TK_OPTION_STRING
465 The value may be any string. The internal form is a (char *)
466 pointer that points to a dynamically allocated copy of the
467 value. This option type supports the TK_OPTION_NULL_OK flag.
468 TK_OPTION_STRING_TABLE
470 For this type, clientData is a pointer to an array of strings
471 suitable for passing to Tcl_GetIndexFromObj. The value must be
472 one of the strings in the table, or a unique abbreviation of one
473 of the strings. The internal form is an integer giving the
474 index into the table of the matching string, like the return
475 value from Tcl_GetStringFromObj.
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
496 option is changed, Tk_SetOptions (or Tk_FreeSavedOptions) will automat‐
497 ically 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
505 invoked; 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
588 options. RestoreProc and freeProc may be NULL, indicating that no
589 function 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
606 explicitly 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
622 option 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
644 tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. RecordPtr is
645 a pointer to the beginning of the widget record to query. InternalOff‐
646 set is the offset in bytes from the beginning of the widget record to
647 the 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
652 restore 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.
658 RestoreProc 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
667 tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr
668 is a pointer to the location where the internal representation of the
669 option 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)