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. Tk_Ini‐
175 tOptions is passed a token for an option table (optionTable) and a
176 pointer to a widget record (recordPtr), which is the C structure that
177 holds information about this widget. Tk_InitOptions uses the informa‐
178 tion in the option table to choose an appropriate default for each
179 option, then it stores the default value directly into the widget
180 record, overwriting any information that was already present in the
181 widget record. Tk_InitOptions normally returns TCL_OK. If an error
182 occurred while setting the default values (e.g., because a default
183 value was erroneous) then TCL_ERROR is returned and an error message is
184 left in interp's result if interp is not NULL.
185 Tk_SetOptions is invoked to modify configuration options based on
187 information specified in a Tcl command. The command might be one that
188 creates a new widget, or a command that modifies options on an existing
189 widget. The objc and objv arguments describe the values of the argu‐
190 ments from the Tcl command. Objv must contain an even number of
191 objects: the first object of each pair gives the name of an option and
192 the second object gives the new value for that option. Tk_SetOptions
193 looks up each name in optionTable, checks that the new value of the
194 option conforms to the type in optionTable, and stores the value of the
195 option into the widget record given by recordPtr. Tk_SetOptions nor‐
196 mally returns TCL_OK. If an error occurred (such as an unknown option
197 name or an illegal option value) then TCL_ERROR is returned and an
198 error message is left in interp's result if interp is not NULL.
199 Tk_SetOptions has two additional features. First, if the maskPtr argu‐
201 ment is not NULL then it points to an integer value that is filled in
202 with information about the options that were modified. For each option
203 in the template passed to Tk_CreateOptionTable there is a typeMask
204 field. The bits of this field are defined by the code that implements
205 the widget; for example, each bit might correspond to a particular con‐
206 figuration option. Alternatively, bits might be used functionally.
207 For example, one bit might be used for redisplay: all options that
208 affect the widget's display, such that changing the option requires the
209 widget to be redisplayed, might have that bit set. Another bit might
210 indicate that the geometry of the widget must be recomputed, and so on.
211 Tk_SetOptions OR's together the typeMask fields from all the options
212 that were modified and returns this value at *maskPtr; the caller can
213 then use this information to optimize itself so that, for example, it
214 does not redisplay the widget if the modified options do not affect the
215 widget's appearance.
216 The second additional feature of Tk_SetOptions has to do with error
218 recovery. If an error occurs while processing configuration options,
219 this feature makes it possible to restore all the configuration options
220 to their previous values. Errors can occur either while processing
221 options in Tk_SetOptions or later in the caller. In many cases the
222 caller does additional processing after Tk_SetOptions returns; for
223 example, it might use an option value to set a trace on a variable and
224 may detect an error if the variable is an array instead of a scalar.
225 Error recovery is enabled by passing in a non-NULL value for the
226 savePtr argument to Tk_SetOptions; this should be a pointer to an
227 uninitialized Tk_SavedOptions structure on the caller's stack.
228 Tk_SetOptions overwrites the structure pointed to by savePtr with
229 information about the old values of any options modified by the proce‐
230 dure. If Tk_SetOptions returns successfully, the caller uses the
231 structure in one of two ways. If the caller completes its processing
232 of the new options without any errors, then it must pass the structure
233 to Tk_FreeSavedOptions so that the old values can be freed. If the
234 caller detects an error in its processing of the new options, then it
235 should pass the structure to Tk_RestoreSavedOptions, which will copy
236 the old values back into the widget record and free the new values. If
237 Tk_SetOptions detects an error then it automatically restores any
238 options that had already been modified and leaves *savePtr in an empty
239 state: the caller need not call either Tk_FreeSavedOptions or
240 Tk_RestoreSavedOptions. If the savePtr argument to Tk_SetOptions is
241 NULL then Tk_SetOptions frees each old option value immediately when it
242 sets a new value for the option. In this case, if an error occurs in
243 the third option, the old values for the first two options cannot be
244 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
249 extract its value from the widget record pointed to by recordPtr, then
250 it returns an object containing that value. If an error occurs (e.g.,
251 because 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.,
269 because 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
274 options 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
284 The array of Tk_OptionSpec structures passed to Tk_CreateOptionTable
285 via its templatePtr argument describes the configuration options sup‐
286 ported by a particular class of widgets. Each structure specifies one
287 configuration option and has the following fields:
288 typedef struct {
289 Tk_OptionType type;
290 const char *optionName;
291 const char *dbName;
292 const char *dbClass;
293 const char *defValue;
294 int objOffset;
295 int internalOffset;
296 int flags;
297 ClientData clientData;
298 int typeMask;
299 } Tk_OptionSpec;
300 The type field indicates what kind of configuration option this is
301 (e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for an inte‐
302 ger value). Type determines how the value of the option is parsed
303 (more on this below). The optionName field is a string such as -font
304 or -bg; it is the name used for the option in Tcl commands and passed
305 to procedures via the objc or namePtr arguments. The dbName and
306 dbClass fields are used by Tk_InitOptions to look up a default value
307 for this option in the option database; if dbName is NULL then the
308 option database is not used by Tk_InitOptions for this option. The
309 defValue field specifies a default value for this configuration option
310 if no value is specified in the option database. The objOffset and
311 internalOffset fields indicate where to store the value of this option
312 in widget records (more on this below); values for the objOffset and
313 internalOffset fields should always be generated with the Tk_Offset
314 macro. The flags field contains additional information to control the
315 processing of this configuration option (see below for details).
316 ClientData provides additional type-specific data needed by certain
317 types. For instance, for TK_OPTION_COLOR types, clientData is a string
318 giving the default value to use on monochrome displays. See the
319 descriptions of the different types below for details. The last field,
320 typeMask, is used by Tk_SetOptions to return information about which
321 options were modified; see the description of Tk_SetOptions above for
322 details.
323 When Tk_InitOptions and Tk_SetOptions store the value of an option into
325 the widget record, they can do it in either of two ways. If the
326 objOffset field of the Tk_OptionSpec is greater than or equal to zero,
327 then the value of the option is stored as a (Tcl_Obj *) at the location
328 in the widget record given by objOffset. If the internalOffset field
329 of the Tk_OptionSpec is greater than or equal to zero, then the value
330 of the option is stored in a type-specific internal form at the loca‐
331 tion in the widget record given by internalOffset. For example, if the
332 option's type is TK_OPTION_INT then the internal form is an integer.
333 If the objOffset or internalOffset field is negative then the value is
334 not stored in that form. At least one of the offsets must be greater
335 than or equal to zero.
336 The flags field consists of one or more bits ORed together. At present
338 only a single flag is supported: TK_OPTION_NULL_OK. If this bit is set
339 for an option then an empty string will be accepted as the value for
340 the option and the resulting internal form will be a NULL pointer, a
341 zero value, or None, depending on the type of the option. If the flag
342 is not set then empty strings will result in errors. TK_OPTION_NULL_OK
343 is typically used to allow a feature to be turned off entirely, e.g.
344 set a cursor value to None so that a window simply inherits its par‐
345 ent's cursor. Not all option types support the TK_OPTION_NULL_OK flag;
346 for those that do, there is an explicit indication of that fact in the
347 descriptions below.
348 The type field of each Tk_OptionSpec structure determines how to parse
350 the value of that configuration option. The legal value for type, and
351 the corresponding actions, are described below. If the type requires a
352 tkwin value to be passed into procedures like Tk_SetOptions, or if it
353 uses the clientData field of the Tk_OptionSpec, then it is indicated
354 explicitly; if not mentioned, the type requires neither tkwin nor
355 clientData.
356 TK_OPTION_ANCHOR
358 The value must be a standard anchor position such as ne or cen‐
359 ter. The internal form is a Tk_Anchor value like the ones
360 returned by Tk_GetAnchorFromObj.
361 TK_OPTION_BITMAP
363 The value must be a standard Tk bitmap name. The internal form
364 is a Pixmap token like the ones returned by Tk_AllocBitmapFro‐
365 mObj. This option type requires tkwin to be supplied to proce‐
366 dures such as Tk_SetOptions, and it supports the
367 TK_OPTION_NULL_OK flag.
368 TK_OPTION_BOOLEAN
370 The value must be a standard boolean value such as true or no.
371 The internal form is an integer with value 0 or 1.
372 TK_OPTION_BORDER
374 The value must be a standard color name such as red or #ff8080.
375 The internal form is a Tk_3DBorder token like the ones returned
376 by Tk_Alloc3DBorderFromObj. This option type requires tkwin to
377 be supplied to procedures such as Tk_SetOptions, and it supports
378 the TK_OPTION_NULL_OK flag.
379 TK_OPTION_COLOR
381 The value must be a standard color name such as red or #ff8080.
382 The internal form is an (XColor *) token like the ones returned
383 by Tk_AllocColorFromObj. This option type requires tkwin to be
384 supplied to procedures such as Tk_SetOptions, and it supports
385 the TK_OPTION_NULL_OK flag.
386 TK_OPTION_CURSOR
388 The value must be a standard cursor name such as cross or @foo.
389 The internal form is a Tk_Cursor token like the ones returned by
390 Tk_AllocCursorFromObj. This option type requires tkwin to be
391 supplied to procedures such as Tk_SetOptions, and when the
392 option is set the cursor for the window is changed by calling
393 XDefineCursor. This option type also supports the
394 TK_OPTION_NULL_OK flag.
395 TK_OPTION_CUSTOM
397 This option allows applications to define new option types. The
398 clientData field of the entry points to a structure defining the
399 new option type. See the section CUSTOM OPTION TYPES below for
400 details.
401 TK_OPTION_DOUBLE
403 The string value must be a floating-point number in the format
404 accepted by strtol. The internal form is a C double value.
405 This option type supports the TK_OPTION_NULL_OK flag; if a NULL
406 value is set, the internal representation is set to zero.
407 TK_OPTION_END
409 Marks the end of the template. There must be a Tk_OptionSpec
410 structure with type TK_OPTION_END at the end of each template.
411 If the clientData field of this structure is not NULL, then it
412 points to an additional array of Tk_OptionSpec's, which is
413 itself terminated by another TK_OPTION_END entry. Templates may
414 be chained arbitrarily deeply. This feature allows common
415 options to be shared by several widget classes.
416 TK_OPTION_FONT
418 The value must be a standard font name such as Times 16. The
419 internal form is a Tk_Font handle like the ones returned by
420 Tk_AllocFontFromObj. This option type requires tkwin to be sup‐
421 plied to procedures such as Tk_SetOptions, and it supports the
422 TK_OPTION_NULL_OK flag.
423 TK_OPTION_INT
425 The string value must be an integer in the format accepted by
426 strtol (e.g. 0 and 0x prefixes may be used to specify octal or
427 hexadecimal numbers, respectively). The internal form is a C
428 int value.
429 TK_OPTION_JUSTIFY
431 The value must be a standard justification value such as left.
432 The internal form is a Tk_Justify like the values returned by
433 Tk_GetJustifyFromObj.
434 TK_OPTION_PIXELS
436 The value must specify a screen distance such as 2i or 6.4. The
437 internal form is an integer value giving a distance in pixels,
438 like the values returned by Tk_GetPixelsFromObj. Note: if the
439 objOffset field is not used then information about the original
440 value of this option will be lost. See OBJOFFSET VS. INTER‐
441 NALOFFSET below for details. This option type supports the
442 TK_OPTION_NULL_OK flag; if a NULL value is set, the internal
443 representation is set to zero.
444 TK_OPTION_RELIEF
446 The value must be standard relief such as raised. The internal
447 form is an integer relief value such as TK_RELIEF_RAISED. This
448 option type supports the TK_OPTION_NULL_OK flag; if the empty
449 string is specified as the value for the option, the integer
450 relief value is set to TK_RELIEF_NULL.
451 TK_OPTION_STRING
453 The value may be any string. The internal form is a (char *)
454 pointer that points to a dynamically allocated copy of the
455 value. This option type supports the TK_OPTION_NULL_OK flag.
456 TK_OPTION_STRING_TABLE
458 For this type, clientData is a pointer to an array of strings
459 suitable for passing to Tcl_GetIndexFromObj. The value must be
460 one of the strings in the table, or a unique abbreviation of one
461 of the strings. The internal form is an integer giving the
462 index into the table of the matching string, like the return
463 value from Tcl_GetStringFromObj.
464 TK_OPTION_SYNONYM
466 This type is used to provide alternative names for an option
467 (for example, -bg is often used as a synonym for -background).
468 The clientData field is a (char *) pointer that gives the name
469 of another option in the same table. Whenever the synonym
470 option is used, the information from the other option will be
471 used instead.
472 TK_OPTION_WINDOW
474 The value must be a window path name. The internal form is a
475 Tk_Window token for the window. This option type requires tkwin
476 to be supplied to procedures such as Tk_SetOptions (in order to
477 identify the application), and it supports the TK_OPTION_NULL_OK
478 flag.
479
482 If a field of a widget record has its offset stored in the objOffset or
483 internalOffset field of a Tk_OptionSpec structure then the procedures
484 described here will handle all of the storage allocation and resource
485 management issues associated with the field. When the value of an
486 option is changed, Tk_SetOptions (or Tk_FreeSavedOptions) will automat‐
487 ically free any resources associated with the old value, such as
488 Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for
489 TK_OPTION_STRING options. For an option stored as an object using the
490 objOffset field of a Tk_OptionSpec, the widget record shares the object
491 pointed to by the objv value from the call to Tk_SetOptions. The ref‐
492 erence count for this object is incremented when a pointer to it is
493 stored in the widget record and decremented when the option is modi‐
494 fied. When the widget is deleted Tk_FreeConfigOptions should be
495 invoked; it will free the resources associated with all options and
496 decrement reference counts for any objects.
497 However, the widget code is responsible for storing NULL or None in all
499 pointer and token fields before invoking Tk_InitOptions. This is
500 needed to allow proper cleanup in the rare case where an error occurs
501 in Tk_InitOptions.
502
505 In most cases it is simplest to use the internalOffset field of a
506 Tk_OptionSpec structure and not the objOffset field. This makes the
507 internal form of the value immediately available to the widget code so
508 the value does not have to be extracted from an object each time it is
509 used. However, there are two cases where the objOffset field is use‐
510 ful. The first case is for TK_OPTION_PIXELS options. In this case,
511 the internal form is an integer pixel value that is valid only for a
512 particular screen. If the value of the option is retrieved, it will be
513 returned as a simple number. For example, after the command .b config‐
514 ure -borderwidth 2m, the command .b configure -borderwidth might return
515 7, which is the integer pixel value corresponding to 2m. Unfortu‐
516 nately, this loses the original screen-independent value. Thus for
517 TK_OPTION_PIXELS options it is better to use the objOffset field. In
518 this case the original value of the option is retained in the object
519 and can be returned when the option is retrieved. In most cases it is
520 convenient to use the internalOffset field as well, so that the integer
521 value is immediately available for use in the widget code (alterna‐
522 tively, Tk_GetPixelsFromObj can be used to extract the integer value
523 from the object whenever it is needed). Note: the problem of losing
524 information on retrievals exists only for TK_OPTION_PIXELS options.
525 The second reason to use the objOffset field is in order to implement
527 new types of options not supported by these procedures. To implement a
528 new type of option, you can use TK_OPTION_STRING as the type in the
529 Tk_OptionSpec structure and set the objOffset field but not the inter‐
530 nalOffset field. Then, after calling Tk_SetOptions, convert the object
531 to internal form yourself.
532
535 Applications can extend the built-in configuration types with addi‐
536 tional configuration types by writing procedures to parse, print, free,
537 and restore saved copies of the type and creating a structure pointing
538 to those procedures:
539 typedef struct Tk_ObjCustomOption {
540 char *name;
541 Tk_CustomOptionSetProc *setProc;
542 Tk_CustomOptionGetProc *getProc;
543 Tk_CustomOptionRestoreProc *restoreProc;
544 Tk_CustomOptionFreeProc *freeProc;
545 ClientData clientData;
546 } Tk_ObjCustomOption;
547 typedef int Tk_CustomOptionSetProc(
549 ClientData clientData,
550 Tcl_Interp *interp,
551 Tk_Window tkwin,
552 Tcl_Obj **valuePtr,
553 char *recordPtr,
554 int internalOffset,
555 char *saveInternalPtr,
556 int flags);
557 typedef Tcl_Obj *Tk_CustomOptionGetProc(
559 ClientData clientData,
560 Tk_Window tkwin,
561 char *recordPtr,
562 int internalOffset);
563 typedef void Tk_CustomOptionRestoreProc(
565 ClientData clientData,
566 Tk_Window tkwin,
567 char *internalPtr,
568 char *saveInternalPtr);
569 typedef void Tk_CustomOptionFreeProc(
571 ClientData clientData,
572 Tk_Window tkwin,
573 char *internalPtr);
574 The Tk_ObjCustomOption structure contains six fields: a name for the
576 custom option type; pointers to the four procedures; and a clientData
577 value to be passed to those procedures when they are invoked. The
578 clientData value typically points to a structure containing information
579 that is needed by the procedures when they are parsing and printing
580 options. RestoreProc and freeProc may be NULL, indicating that no
581 function should be called for those operations.
582 The setProc procedure is invoked by Tk_SetOptions to convert a Tcl_Obj
584 into an internal representation and store the resulting value in the
585 widget record. The arguments are:
586 clientData
588 A copy of the clientData field in the Tk_ObjCustomOption
589 structure.
590 interp A pointer to a Tcl interpreter, used for error reporting.
592 Tkwin A copy of the tkwin argument to Tk_SetOptions
594 valuePtr
596 A pointer to a reference to a Tcl_Obj describing the new
597 value for the option; it could have been specified
598 explicitly in the call to Tk_SetOptions or it could come
599 from the option database or a default. If the objOffset
600 for the option is non-negative (the option value is
601 stored as a (Tcl_Obj *) in the widget record), the
602 Tcl_Obj pointer referenced by valuePtr is the pointer
603 that will be stored at the objOffset for the option.
604 SetProc may modify the value if necessary; for example,
605 setProc may change the value to NULL to support the
606 TK_OPTION_NULL_OK flag.
607 recordPtr
609 A pointer to the start of the widget record to modify.
610 internalOffset
612 Offset in bytes from the start of the widget record to
613 the location where the internal representation of the
614 option value is to be placed.
615 saveInternalPtr
617 A pointer to storage allocated in a Tk_SavedOptions
618 structure for the internal representation of the original
619 option value. Before setting the option to its new
620 value, setProc should set the value referenced by saveIn‐
621 ternalPtr to the original value of the option in order to
622 support Tk_RestoreSavedOptions.
623 flags A copy of the flags field in the Tk_OptionSpec structure
625 for the option
626 SetProc returns a standard Tcl result: TCL_OK to indicate successful
628 processing, or TCL_ERROR to indicate a failure of any kind. An error
629 message may be left in the Tcl interpreter given by interp in the case
630 of an error.
631 The getProc procedure is invoked by Tk_GetOptionValue and Tk_GetOption‐
633 Info to retrieve a Tcl_Obj representation of the internal representa‐
634 tion of an option. The clientData argument is a copy of the clientData
635 field in the Tk_ObjCustomOption structure. Tkwin is a copy of the
636 tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. RecordPtr is
637 a pointer to the beginning of the widget record to query. InternalOff‐
638 set is the offset in bytes from the beginning of the widget record to
639 the location where the internal representation of the option value is
640 stored. GetProc must return a pointer to a Tcl_Obj representing the
641 value of the option.
642 The restoreProc procedure is invoked by Tk_RestoreSavedOptions to
644 restore a previously saved internal representation of a custom option
645 value. The clientData argument is a copy of the clientData field in
646 the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argu‐
647 ment to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr is a
648 pointer to the location where internal representation of the option
649 value is stored. SaveInternalPtr is a pointer to the saved value.
650 RestoreProc must copy the value from saveInternalPtr to internalPtr to
651 restore the value. RestoreProc need not free any memory associated
652 with either internalPtr or saveInternalPtr; freeProc will be invoked to
653 free that memory if necessary. RestoreProc has no return value.
654 The freeProc procedure is invoked by Tk_SetOptions and Tk_FreeSavedOp‐
656 tions to free any storage allocated for the internal representation of
657 a custom option. The clientData argument is a copy of the clientData
658 field in the Tk_ObjCustomOption structure. Tkwin is a copy of the
659 tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr
660 is a pointer to the location where the internal representation of the
661 option value is stored. The freeProc must free any storage associated
662 with the option. FreeProc has no return value.
663
667 anchor, bitmap, boolean, border, color, configuration option, cursor,
668 double, font, integer, justify, pixels, relief, screen distance, syn‐
669 onym
670Tk 8.1 Tk_SetOptions(3)