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
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 ClientData 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
305 dbClass fields are used by Tk_InitOptions to look up a default value
306 for this option in the option database; if dbName is NULL then the
307 option database is not used by Tk_InitOptions for this option. The
308 defValue field specifies a default value for this configuration option
309 if no value is specified in the option database. The objOffset and
310 internalOffset fields indicate where to store the value of this option
311 in widget records (more on this below); values for the objOffset and
312 internalOffset 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
318 descriptions 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
325 objOffset 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. At present
337 only a single flag is supported: TK_OPTION_NULL_OK. If this bit is set
338 for an option then an empty string will be accepted as the value for
339 the option and the resulting internal form will be a NULL pointer, a
340 zero value, or None, depending on the type of the option. If the flag
341 is not set then empty strings will result in errors. TK_OPTION_NULL_OK
342 is typically used to allow a feature to be turned off entirely, e.g.
343 set a cursor value to None so that a window simply inherits its par‐
344 ent's cursor. Not all option types support the TK_OPTION_NULL_OK flag;
345 for those that do, there is an explicit indication of that fact in the
346 descriptions below.
347 The type field of each Tk_OptionSpec structure determines how to parse
349 the value of that configuration option. The legal value for type, and
350 the corresponding actions, are described below. If the type requires a
351 tkwin value to be passed into procedures like Tk_SetOptions, or if it
352 uses the clientData field of the Tk_OptionSpec, then it is indicated
353 explicitly; if not mentioned, the type requires neither tkwin nor
354 clientData.
355 TK_OPTION_ANCHOR
357 The value must be a standard anchor position such as ne or cen‐
358 ter. The internal form is a Tk_Anchor value like the ones
359 returned by Tk_GetAnchorFromObj.
360 TK_OPTION_BITMAP
362 The value must be a standard Tk bitmap name. The internal form
363 is a Pixmap token like the ones returned by Tk_AllocBitmapFro‐
364 mObj. This option type requires tkwin to be supplied to proce‐
365 dures such as Tk_SetOptions, and it supports the
366 TK_OPTION_NULL_OK flag.
367 TK_OPTION_BOOLEAN
369 The value must be a standard boolean value such as true or no.
370 The internal form is an integer with value 0 or 1.
371 TK_OPTION_BORDER
373 The value must be a standard color name such as red or #ff8080.
374 The internal form is a Tk_3DBorder token like the ones returned
375 by Tk_Alloc3DBorderFromObj. This option type requires tkwin to
376 be supplied to procedures such as Tk_SetOptions, and it supports
377 the TK_OPTION_NULL_OK flag.
378 TK_OPTION_COLOR
380 The value must be a standard color name such as red or #ff8080.
381 The internal form is an (XColor *) token like the ones returned
382 by Tk_AllocColorFromObj. This option type requires tkwin to be
383 supplied to procedures such as Tk_SetOptions, and it supports
384 the TK_OPTION_NULL_OK flag.
385 TK_OPTION_CURSOR
387 The value must be a standard cursor name such as cross or @foo.
388 The internal form is a Tk_Cursor token like the ones returned by
389 Tk_AllocCursorFromObj. This option type requires tkwin to be
390 supplied to procedures such as Tk_SetOptions, and when the
391 option is set the cursor for the window is changed by calling
392 XDefineCursor. This option type also supports the
393 TK_OPTION_NULL_OK flag.
394 TK_OPTION_CUSTOM
396 This option allows applications to define new option types. The
397 clientData field of the entry points to a structure defining the
398 new option type. See the section CUSTOM OPTION TYPES below for
399 details.
400 TK_OPTION_DOUBLE
402 The string value must be a floating-point number in the format
403 accepted by strtol. The internal form is a C double value.
404 This option type supports the TK_OPTION_NULL_OK flag; if a NULL
405 value is set, the internal representation is set to zero.
406 TK_OPTION_END
408 Marks the end of the template. There must be a Tk_OptionSpec
409 structure with type TK_OPTION_END at the end of each template.
410 If the clientData field of this structure is not NULL, then it
411 points to an additional array of Tk_OptionSpec's, which is
412 itself terminated by another TK_OPTION_END entry. Templates may
413 be chained arbitrarily deeply. This feature allows common
414 options to be shared by several widget classes.
415 TK_OPTION_FONT
417 The value must be a standard font name such as Times 16. The
418 internal form is a Tk_Font handle like the ones returned by
419 Tk_AllocFontFromObj. This option type requires tkwin to be sup‐
420 plied to procedures such as Tk_SetOptions, and it supports the
421 TK_OPTION_NULL_OK flag.
422 TK_OPTION_INT
424 The string value must be an integer in the format accepted by
425 strtol (e.g. 0 and 0x prefixes may be used to specify octal or
426 hexadecimal numbers, respectively). The internal form is a C
427 int value.
428 TK_OPTION_JUSTIFY
430 The value must be a standard justification value such as left.
431 The internal form is a Tk_Justify like the values returned by
432 Tk_GetJustifyFromObj.
433 TK_OPTION_PIXELS
435 The value must specify a screen distance such as 2i or 6.4. The
436 internal form is an integer value giving a distance in pixels,
437 like the values returned by Tk_GetPixelsFromObj. Note: if the
438 objOffset field is not used then information about the original
439 value of this option will be lost. See OBJOFFSET VS. INTER‐
440 NALOFFSET below for details. This option type supports the
441 TK_OPTION_NULL_OK flag; if a NULL value is set, the internal
442 representation is set to zero.
443 TK_OPTION_RELIEF
445 The value must be standard relief such as raised. The internal
446 form is an integer relief value such as TK_RELIEF_RAISED. This
447 option type supports the TK_OPTION_NULL_OK flag; if the empty
448 string is specified as the value for the option, the integer
449 relief value is set to TK_RELIEF_NULL.
450 TK_OPTION_STRING
452 The value may be any string. The internal form is a (char *)
453 pointer that points to a dynamically allocated copy of the
454 value. This option type supports the TK_OPTION_NULL_OK flag.
455 TK_OPTION_STRING_TABLE
457 For this type, clientData is a pointer to an array of strings
458 suitable for passing to Tcl_GetIndexFromObj. The value must be
459 one of the strings in the table, or a unique abbreviation of one
460 of the strings. The internal form is an integer giving the
461 index into the table of the matching string, like the return
462 value from Tcl_GetStringFromObj.
463 TK_OPTION_SYNONYM
465 This type is used to provide alternative names for an option
466 (for example, -bg is often used as a synonym for -background).
467 The clientData field is a string that gives the name of another
468 option in the same table. Whenever the synonym option is used,
469 the information from the other option will be used instead.
470 TK_OPTION_WINDOW
472 The value must be a window path name. The internal form is a
473 Tk_Window token for the window. This option type requires tkwin
474 to be supplied to procedures such as Tk_SetOptions (in order to
475 identify the application), and it supports the TK_OPTION_NULL_OK
476 flag.
477
479 If a field of a widget record has its offset stored in the objOffset or
480 internalOffset field of a Tk_OptionSpec structure then the procedures
481 described here will handle all of the storage allocation and resource
482 management issues associated with the field. When the value of an
483 option is changed, Tk_SetOptions (or Tk_FreeSavedOptions) will automat‐
484 ically free any resources associated with the old value, such as
485 Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for
486 TK_OPTION_STRING options. For an option stored as an object using the
487 objOffset field of a Tk_OptionSpec, the widget record shares the object
488 pointed to by the objv value from the call to Tk_SetOptions. The ref‐
489 erence count for this object is incremented when a pointer to it is
490 stored in the widget record and decremented when the option is modi‐
491 fied. When the widget is deleted Tk_FreeConfigOptions should be
492 invoked; it will free the resources associated with all options and
493 decrement reference counts for any objects.
494 However, the widget code is responsible for storing NULL or None in all
496 pointer and token fields before invoking Tk_InitOptions. This is
497 needed to allow proper cleanup in the rare case where an error occurs
498 in Tk_InitOptions.
499
501 In most cases it is simplest to use the internalOffset field of a
502 Tk_OptionSpec structure and not the objOffset field. This makes the
503 internal form of the value immediately available to the widget code so
504 the value does not have to be extracted from an object each time it is
505 used. However, there are two cases where the objOffset field is use‐
506 ful. The first case is for TK_OPTION_PIXELS options. In this case,
507 the internal form is an integer pixel value that is valid only for a
508 particular screen. If the value of the option is retrieved, it will be
509 returned as a simple number. For example, after the command .b config‐
510 ure -borderwidth 2m, the command .b configure -borderwidth might return
511 7, which is the integer pixel value corresponding to 2m. Unfortu‐
512 nately, this loses the original screen-independent value. Thus for
513 TK_OPTION_PIXELS options it is better to use the objOffset field. In
514 this case the original value of the option is retained in the object
515 and can be returned when the option is retrieved. In most cases it is
516 convenient to use the internalOffset field as well, so that the integer
517 value is immediately available for use in the widget code (alterna‐
518 tively, Tk_GetPixelsFromObj can be used to extract the integer value
519 from the object whenever it is needed). Note: the problem of losing
520 information on retrievals exists only for TK_OPTION_PIXELS options.
521 The second reason to use the objOffset field is in order to implement
523 new types of options not supported by these procedures. To implement a
524 new type of option, you can use TK_OPTION_STRING as the type in the
525 Tk_OptionSpec structure and set the objOffset field but not the inter‐
526 nalOffset field. Then, after calling Tk_SetOptions, convert the object
527 to internal form yourself.
528
530 Applications can extend the built-in configuration types with addi‐
531 tional configuration types by writing procedures to parse, print, free,
532 and restore saved copies of the type and creating a structure pointing
533 to those procedures:
534 typedef struct Tk_ObjCustomOption {
535 char *name;
536 Tk_CustomOptionSetProc *setProc;
537 Tk_CustomOptionGetProc *getProc;
538 Tk_CustomOptionRestoreProc *restoreProc;
539 Tk_CustomOptionFreeProc *freeProc;
540 ClientData clientData;
541 } Tk_ObjCustomOption;
542 typedef int Tk_CustomOptionSetProc(
544 ClientData clientData,
545 Tcl_Interp *interp,
546 Tk_Window tkwin,
547 Tcl_Obj **valuePtr,
548 char *recordPtr,
549 int internalOffset,
550 char *saveInternalPtr,
551 int flags);
552 typedef Tcl_Obj *Tk_CustomOptionGetProc(
554 ClientData clientData,
555 Tk_Window tkwin,
556 char *recordPtr,
557 int internalOffset);
558 typedef void Tk_CustomOptionRestoreProc(
560 ClientData clientData,
561 Tk_Window tkwin,
562 char *internalPtr,
563 char *saveInternalPtr);
564 typedef void Tk_CustomOptionFreeProc(
566 ClientData clientData,
567 Tk_Window tkwin,
568 char *internalPtr);
569 The Tk_ObjCustomOption structure contains six fields: a name for the
571 custom option type; pointers to the four procedures; and a clientData
572 value to be passed to those procedures when they are invoked. The
573 clientData value typically points to a structure containing information
574 that is needed by the procedures when they are parsing and printing
575 options. RestoreProc and freeProc may be NULL, indicating that no
576 function should be called for those operations.
577 The setProc procedure is invoked by Tk_SetOptions to convert a Tcl_Obj
579 into an internal representation and store the resulting value in the
580 widget record. The arguments are:
581 clientData
583 A copy of the clientData field in the Tk_ObjCustomOption
584 structure.
585 interp A pointer to a Tcl interpreter, used for error reporting.
587 Tkwin A copy of the tkwin argument to Tk_SetOptions
589 valuePtr
591 A pointer to a reference to a Tcl_Obj describing the new
592 value for the option; it could have been specified
593 explicitly in the call to Tk_SetOptions or it could come
594 from the option database or a default. If the objOffset
595 for the option is non-negative (the option value is
596 stored as a (Tcl_Obj *) in the widget record), the
597 Tcl_Obj pointer referenced by valuePtr is the pointer
598 that will be stored at the objOffset for the option.
599 SetProc may modify the value if necessary; for example,
600 setProc may change the value to NULL to support the
601 TK_OPTION_NULL_OK flag.
602 recordPtr
604 A pointer to the start of the widget record to modify.
605 internalOffset
607 Offset in bytes from the start of the widget record to
608 the location where the internal representation of the
609 option value is to be placed.
610 saveInternalPtr
612 A pointer to storage allocated in a Tk_SavedOptions
613 structure for the internal representation of the original
614 option value. Before setting the option to its new
615 value, setProc should set the value referenced by saveIn‐
616 ternalPtr to the original value of the option in order to
617 support Tk_RestoreSavedOptions.
618 flags A copy of the flags field in the Tk_OptionSpec structure
620 for the option
621 SetProc returns a standard Tcl result: TCL_OK to indicate successful
623 processing, or TCL_ERROR to indicate a failure of any kind. An error
624 message may be left in the Tcl interpreter given by interp in the case
625 of an error.
626 The getProc procedure is invoked by Tk_GetOptionValue and Tk_GetOption‐
628 Info to retrieve a Tcl_Obj representation of the internal representa‐
629 tion of an option. The clientData argument is a copy of the clientData
630 field in the Tk_ObjCustomOption structure. Tkwin is a copy of the
631 tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. RecordPtr is
632 a pointer to the beginning of the widget record to query. InternalOff‐
633 set is the offset in bytes from the beginning of the widget record to
634 the location where the internal representation of the option value is
635 stored. GetProc must return a pointer to a Tcl_Obj representing the
636 value of the option.
637 The restoreProc procedure is invoked by Tk_RestoreSavedOptions to
639 restore a previously saved internal representation of a custom option
640 value. The clientData argument is a copy of the clientData field in
641 the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argu‐
642 ment to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr is a
643 pointer to the location where internal representation of the option
644 value is stored. SaveInternalPtr is a pointer to the saved value.
645 RestoreProc must copy the value from saveInternalPtr to internalPtr to
646 restore the value. RestoreProc need not free any memory associated
647 with either internalPtr or saveInternalPtr; freeProc will be invoked to
648 free that memory if necessary. RestoreProc has no return value.
649 The freeProc procedure is invoked by Tk_SetOptions and Tk_FreeSavedOp‐
651 tions to free any storage allocated for the internal representation of
652 a custom option. The clientData argument is a copy of the clientData
653 field in the Tk_ObjCustomOption structure. Tkwin is a copy of the
654 tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr
655 is a pointer to the location where the internal representation of the
656 option value is stored. The freeProc must free any storage associated
657 with the option. FreeProc has no return value.
658
660 anchor, bitmap, boolean, border, color, configuration option, cursor,
661 double, font, integer, justify, pixels, relief, screen distance, syn‐
662 onym
663Tk 8.1 Tk_SetOptions(3)