1Tk_SetOptions(3)             Tk Library Procedures            Tk_SetOptions(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

14       #include <tk.h>
15
16       Tk_OptionTable
17       Tk_CreateOptionTable(interp, templatePtr)
18
19       Tk_DeleteOptionTable(optionTable)
20
21       int
22       Tk_InitOptions(interp, recordPtr, optionTable, tkwin)
23
24       int
25       Tk_SetOptions(interp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr)
26
27       Tk_FreeSavedOptions(savedPtr)
28
29       Tk_RestoreSavedOptions(savedPtr)
30
31       Tcl_Obj *
32       Tk_GetOptionValue(interp, recordPtr, optionTable, namePtr, tkwin)
33
34       Tcl_Obj *
35       Tk_GetOptionInfo(interp, recordPtr, optionTable, namePtr, tkwin)
36
37       Tk_FreeConfigOptions(recordPtr, optionTable, tkwin)
38
39       int
40       Tk_Offset(type, field)
41

ARGUMENTS

43       Tcl_Interp *interp (in)                     A  Tcl  interpreter.   Most
44                                                   procedures  use  this  only
45                                                   for  returning  error  mes‐
46                                                   sages;  if  it is NULL then
47                                                   no error messages  are  re‐
48                                                   turned.   For  Tk_CreateOp‐
49                                                   tionTable the value  cannot
50                                                   be  NULL;  it gives the in‐
51                                                   terpreter in which the  op‐
52                                                   tion table will be used.
53
54       const Tk_OptionSpec *templatePtr (in)       Points   to   an  array  of
55                                                   static information that de‐
56                                                   scribes  the  configuration
57                                                   options that are supported.
58                                                   Used   to  build  a  Tk_Op‐
59                                                   tionTable.  The information
60                                                   pointed to by this argument
61                                                   must exist for the lifetime
62                                                   of the Tk_OptionTable.
63
64       Tk_OptionTable optionTable (in)             Token  for an option table.
65                                                   Must have been returned  by
66                                                   a  previous call to Tk_Cre‐
67                                                   ateOptionTable.
68
69       char *recordPtr (in/out)                    Points  to   structure   in
70                                                   which  values of configura‐
71                                                   tion  options  are  stored;
72                                                   fields  of  this record are
73                                                   modified by procedures such
74                                                   as  Tk_SetOptions  and read
75                                                   by   procedures   such   as
76                                                   Tk_GetOptionValue.
77
78       Tk_Window tkwin (in)                        For  options such as TK_OP‐
79                                                   TION_COLOR,  this  argument
80                                                   indicates   the  window  in
81                                                   which the  option  will  be
82                                                   used.   If optionTable uses
83                                                   no   window-dependent   op‐
84                                                   tions,  then  a  NULL value
85                                                   may be  supplied  for  this
86                                                   argument.
87
88       int objc (in)                               Number of values in objv.
89
90       Tcl_Obj *const *objv (in)                   Command-line  arguments for
91                                                   setting   configuring   op‐
92                                                   tions.
93
94       Tk_SavedOptions *savePtr (out)              If  not NULL, the structure
95                                                   pointed to by this argument
96                                                   is  filled  in with the old
97                                                   values of any options  that
98                                                   were  modified and old val‐
99                                                   ues are restored  automati‐
100                                                   cally if an error occurs in
101                                                   Tk_SetOptions.
102
103       int *maskPtr (out)                          If  not  NULL,   the   word
104                                                   pointed  to  by  maskPtr is
105                                                   filled in with the bit-wise
106                                                   OR  of  the typeMask fields
107                                                   for the options  that  were
108                                                   modified.
109
110       Tk_SavedOptions *savedPtr (in/out)          Points  to a structure pre‐
111                                                   viously filled in by Tk_Se‐
112                                                   tOptions with old values of
113                                                   modified options.
114
115       Tcl_Obj *namePtr (in)                       The value of this object is
116                                                   the  name  of  a particular
117                                                   option.  If NULL is  passed
118                                                   to   Tk_GetOptionInfo  then
119                                                   information is returned for
120                                                   all  options.   Must not be
121                                                   NULL when Tk_GetOptionValue
122                                                   is called.
123
124       type name type (in)                         The  name  of the type of a
125                                                   record.
126
127       field name field (in)                       The  name  of  a  field  in
128                                                   records of type type.
129______________________________________________________________________________
130

DESCRIPTION

132       These  procedures  handle  most of the details of parsing configuration
133       options such as those for Tk widgets.  Given a description of what  op‐
134       tions are supported, these procedures handle all the details of parsing
135       options and storing their values into a C structure associated with the
136       widget or object. The procedures were designed primarily for widgets in
137       Tk, but they can also be used for other kinds of objects that have con‐
138       figuration  options.   In the rest of this manual page “widget” will be
139       used to refer to the object whose options are being managed;  in  prac‐
140       tice the object may not actually be a widget.  The term “widget record”
141       is used to refer to the C-level structure in which information about  a
142       particular widget or object is stored.
143
144       Note:  the  easiest way to learn how to use these procedures is to look
145       at a working example.  In Tk, the simplest example is the code that im‐
146       plements  the  button family of widgets, which is in tkButton.c.  Other
147       examples are in tkSquare.c and tkMenu.c.
148
149       In order to use these procedures, the code that implements  the  widget
150       must contain a static array of Tk_OptionSpec structures. This is a tem‐
151       plate that describes the various options supported  by  that  class  of
152       widget; there is a separate template for each kind of widget.  The tem‐
153       plate contains information such as the name of each option,  its  type,
154       its  default  value, and where the value of the option is stored in the
155       widget record.  See TEMPLATES below for more detail.
156
157       In order to process configuration options efficiently, the static  tem‐
158       plate  must  be augmented with additional information that is available
159       only at runtime.  The procedure Tk_CreateOptionTable creates  this  dy‐
160       namic  information from the template and returns a Tk_OptionTable token
161       that describes both the static and dynamic  information.   All  of  the
162       other procedures, such as Tk_SetOptions, take a Tk_OptionTable token as
163       argument.  Typically, Tk_CreateOptionTable is  called  the  first  time
164       that a widget of a particular class is created and the resulting Tk_Op‐
165       tionTable is used in the future for  all  widgets  of  that  class.   A
166       Tk_OptionTable  may  be used only in a single interpreter, given by the
167       interp argument to Tk_CreateOptionTable.  When an option  table  is  no
168       longer  needed Tk_DeleteOptionTable should be called to free all of its
169       resources.  All of the option tables for a Tcl  interpreter  are  freed
170       automatically if the interpreter is deleted.
171
172       Tk_InitOptions  is  invoked when a new widget is created to set the de‐
173       fault values for all of the widget's configuration options that do  not
174       have  TK_OPTION_DONT_SET_DEFAULT  set in their flags field.  Tk_InitOp‐
175       tions is passed a token for an option table (optionTable) and a pointer
176       to a widget record (recordPtr), which is the C structure that holds in‐
177       formation about this widget.  Tk_InitOptions uses  the  information  in
178       the  option table to choose an appropriate default for each option, ex‐
179       cept those having TK_OPTION_DONT_SET_DEFAULT set, then  it  stores  the
180       default value directly into the widget record, overwriting any informa‐
181       tion that was already present in  the  widget  record.   Tk_InitOptions
182       normally  returns  TCL_OK.   If an error occurred while setting the de‐
183       fault values (e.g., because a default value was erroneous) then TCL_ER‐
184       ROR  is returned and an error message is left in interp's result if in‐
185       terp is not NULL.
186
187       Tk_SetOptions is invoked to modify configuration options based  on  in‐
188       formation  specified  in  a Tcl command.  The command might be one that
189       creates a new widget, or a command that modifies options on an existing
190       widget.   The  objc and objv arguments describe the values of the argu‐
191       ments from the Tcl command.  Objv must contain an even  number  of  ob‐
192       jects:  the  first  object of each pair gives the name of an option and
193       the second object gives the new value for that  option.   Tk_SetOptions
194       looks up each name in optionTable, checks that the new value of the op‐
195       tion conforms to the type in optionTable, and stores the value  of  the
196       option  into  the widget record given by recordPtr.  Tk_SetOptions nor‐
197       mally returns TCL_OK.  If an error occurred (such as an unknown  option
198       name  or an illegal option value) then TCL_ERROR is returned and an er‐
199       ror message is left in interp's result if interp is not NULL.
200
201       Tk_SetOptions has two additional features.  First, if the maskPtr argu‐
202       ment  is  not NULL then it points to an integer value that is filled in
203       with information about the options that were modified.  For each option
204       in  the  template  passed  to  Tk_CreateOptionTable there is a typeMask
205       field.  The bits of this field are defined by the code that  implements
206       the widget; for example, each bit might correspond to a particular con‐
207       figuration option.  Alternatively, bits  might  be  used  functionally.
208       For  example, one bit might be used for redisplay: all options that af‐
209       fect the widget's display, such that changing the option  requires  the
210       widget  to  be redisplayed, might have that bit set.  Another bit might
211       indicate that the geometry of the widget must be recomputed, and so on.
212       Tk_SetOptions  OR's  together  the typeMask fields from all the options
213       that were modified and returns this value at *maskPtr; the  caller  can
214       then  use  this information to optimize itself so that, for example, it
215       does not redisplay the widget if the modified options do not affect the
216       widget's appearance.
217
218       The second additional feature of Tk_SetOptions has to do with error re‐
219       covery.  If an error occurs  while  processing  configuration  options,
220       this feature makes it possible to restore all the configuration options
221       to their previous values.  Errors can occur either while processing op‐
222       tions  in  Tk_SetOptions  or  later  in  the caller.  In many cases the
223       caller does additional processing after Tk_SetOptions returns; for  ex‐
224       ample,  it  might  use an option value to set a trace on a variable and
225       may detect an error if the variable is an array instead  of  a  scalar.
226       Error  recovery  is  enabled  by  passing  in  a non-NULL value for the
227       savePtr argument to Tk_SetOptions; this  should  be  a  pointer  to  an
228       uninitialized  Tk_SavedOptions structure on the caller's stack.  Tk_Se‐
229       tOptions overwrites the structure pointed to by savePtr  with  informa‐
230       tion about the old values of any options modified by the procedure.  If
231       Tk_SetOptions returns successfully, the caller uses  the  structure  in
232       one of two ways.  If the caller completes its processing of the new op‐
233       tions  without  any  errors,  then  it  must  pass  the  structure   to
234       Tk_FreeSavedOptions so that the old values can be freed.  If the caller
235       detects an error in its processing of the new options, then  it  should
236       pass  the  structure to Tk_RestoreSavedOptions, which will copy the old
237       values back into the widget record and free the new values.  If  Tk_Se‐
238       tOptions  detects  an  error then it automatically restores any options
239       that had already been modified and leaves *savePtr in an  empty  state:
240       the  caller need not call either Tk_FreeSavedOptions or Tk_RestoreSave‐
241       dOptions.  If the savePtr argument to Tk_SetOptions is NULL then Tk_Se‐
242       tOptions  frees  each  old  option value immediately when it sets a new
243       value for the option.  In this case, if an error occurs  in  the  third
244       option, the old values for the first two options cannot be restored.
245
246       Tk_GetOptionValue  returns  the current value of a configuration option
247       for a particular widget.  The namePtr argument contains the name of  an
248       option; Tk_GetOptionValue uses optionTable to lookup the option and ex‐
249       tract its value from the widget record pointed to by recordPtr, then it
250       returns an object containing that value.  If an error occurs (e.g., be‐
251       cause namePtr contains an unknown option name) then  NULL  is  returned
252       and an error message is left in interp's result unless interp is NULL.
253
254       Tk_GetOptionInfo  returns  information about configuration options in a
255       form suitable for configure widget commands.  If the  namePtr  argument
256       is not NULL, it points to an object that gives the name of a configura‐
257       tion option; Tk_GetOptionInfo returns an object containing a list  with
258       five  elements,  which  are  the name of the option, the name and class
259       used for the option in the option database, the default value  for  the
260       option,  and the current value for the option.  If the namePtr argument
261       is NULL, then Tk_GetOptionInfo returns information about all options in
262       the  form  of a list of lists; each sublist describes one option.  Syn‐
263       onym options are handled differently depending on  whether  namePtr  is
264       NULL:  if  namePtr is NULL then the sublist for each synonym option has
265       only two elements, which are the name of the option and the name of the
266       other option that it refers to; if namePtr is non-NULL and names a syn‐
267       onym option then the object returned is the five-element list  for  the
268       other option that the synonym refers to.  If an error occurs (e.g., be‐
269       cause namePtr contains an unknown option name) then  NULL  is  returned
270       and an error message is left in interp's result unless interp is NULL.
271
272       Tk_FreeConfigOptions  must  be  invoked  when  a widget is deleted.  It
273       frees all of the resources associated with any of the configuration op‐
274       tions defined in recordPtr by optionTable.
275
276       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

TEMPLATES

283       The  array  of  Tk_OptionSpec structures passed to Tk_CreateOptionTable
284       via its templatePtr argument describes the configuration  options  sup‐
285       ported  by a particular class of widgets.  Each structure specifies one
286       configuration option and has the following fields:
287              typedef struct {
288                  Tk_OptionType type;
289                  const char *optionName;
290                  const char *dbName;
291                  const char *dbClass;
292                  const char *defValue;
293                  int objOffset;
294                  int internalOffset;
295                  int flags;
296                  const void *clientData;
297                  int typeMask;
298              } Tk_OptionSpec;
299       The type field indicates what kind  of  configuration  option  this  is
300       (e.g.  TK_OPTION_COLOR for a color value, or TK_OPTION_INT for an inte‐
301       ger value).  Type determines how the value  of  the  option  is  parsed
302       (more  on  this below).  The optionName field is a string such as -font
303       or -bg; it is the name used for the option in Tcl commands  and  passed
304       to  procedures  via  the objc or namePtr arguments.  The dbName and db‐
305       Class fields are used by Tk_InitOptions to look up a default value  for
306       this  option  in the option database; if dbName is NULL then the option
307       database is not used by Tk_InitOptions for this option.   The  defValue
308       field  specifies  a  default  value for this configuration option if no
309       value is specified in the option database.  The  objOffset  and  inter‐
310       nalOffset  fields  indicate  where to store the value of this option in
311       widget records (more on this below); values for the objOffset  and  in‐
312       ternalOffset  fields  should  always  be  generated  with the Tk_Offset
313       macro.  The flags field contains additional information to control  the
314       processing  of  this  configuration  option  (see  below  for details).
315       ClientData provides additional type-specific  data  needed  by  certain
316       types.  For instance, for TK_OPTION_COLOR types, clientData is a string
317       giving the default value to use on monochrome displays.   See  the  de‐
318       scriptions  of  the different types below for details.  The last field,
319       typeMask, is used by Tk_SetOptions to return  information  about  which
320       options  were  modified; see the description of Tk_SetOptions above for
321       details.
322
323       When Tk_InitOptions and Tk_SetOptions store the value of an option into
324       the  widget  record,  they can do it in either of two ways.  If the ob‐
325       jOffset field of the Tk_OptionSpec is greater than or  equal  to  zero,
326       then the value of the option is stored as a (Tcl_Obj *) at the location
327       in the widget record given by objOffset.  If the  internalOffset  field
328       of  the  Tk_OptionSpec is greater than or equal to zero, then the value
329       of the option is stored in a type-specific internal form at  the  loca‐
330       tion in the widget record given by internalOffset.  For example, if the
331       option's type is TK_OPTION_INT then the internal form  is  an  integer.
332       If  the objOffset or internalOffset field is negative then the value is
333       not stored in that form.  At least one of the offsets must  be  greater
334       than or equal to zero.
335
336       The flags field consists of one or more bits ORed together. The follow‐
337       ing flags are supported:
338
339       TK_OPTION_NULL_OK
340              If this bit is set for an option then an empty  string  will  be
341              accepted  as the value for the option and the resulting internal
342              form will be a NULL pointer, a zero value, or None, depending on
343              the  type  of  the  option.   If  the flag is not set then empty
344              strings will result in errors.  TK_OPTION_NULL_OK  is  typically
345              used  to  allow  a feature to be turned off entirely, e.g. set a
346              cursor value to None so that a window simply inherits  its  par‐
347              ent's   cursor.    Not  all  option  types  support  the  TK_OP‐
348              TION_NULL_OK flag; for those that do, there is an explicit indi‐
349              cation of that fact in the descriptions below.
350
351       TK_OPTION_DONT_SET_DEFAULT
352              If  this  bit is set for an option then no default value will be
353              set in Tk_InitOptions for this option. Neither the option  data‐
354              base,  nor any system default value, nor optionTable are used to
355              give a default value to this option. Instead it is assumed  that
356              the  caller  has  already supplied a default value in the widget
357              code.
358
359       The type field of each Tk_OptionSpec structure determines how to  parse
360       the  value  of that configuration option. The legal value for type, and
361       the corresponding actions, are described below.  If the type requires a
362       tkwin  value  to be passed into procedures like Tk_SetOptions, or if it
363       uses the clientData field of the Tk_OptionSpec, then  it  is  indicated
364       explicitly;  if  not  mentioned,  the  type  requires neither tkwin nor
365       clientData.
366
367       TK_OPTION_ANCHOR
368              The value must be a standard anchor position such as ne or  cen‐
369              ter.   The  internal form is a Tk_Anchor value like the ones re‐
370              turned by Tk_GetAnchorFromObj.
371
372       TK_OPTION_BITMAP
373              The value must be a standard Tk bitmap name. The  internal  form
374              is  a  Pixmap token like the ones returned by Tk_AllocBitmapFro‐
375              mObj.  This option type requires tkwin to be supplied to  proce‐
376              dures   such  as  Tk_SetOptions,  and  it  supports  the  TK_OP‐
377              TION_NULL_OK flag.
378
379       TK_OPTION_BOOLEAN
380              The value must be a standard boolean value such as true  or  no.
381              The internal form is an integer with value 0 or 1.
382
383       TK_OPTION_BORDER
384              The  value must be a standard color name such as red or #ff8080.
385              The internal form is a Tk_3DBorder token like the ones  returned
386              by  Tk_Alloc3DBorderFromObj.  This option type requires tkwin to
387              be supplied to procedures such as Tk_SetOptions, and it supports
388              the TK_OPTION_NULL_OK flag.
389
390       TK_OPTION_COLOR
391              The  value must be a standard color name such as red or #ff8080.
392              The internal form is an (XColor *) token like the ones  returned
393              by  Tk_AllocColorFromObj.  This option type requires tkwin to be
394              supplied to procedures such as Tk_SetOptions,  and  it  supports
395              the TK_OPTION_NULL_OK flag.
396
397       TK_OPTION_CURSOR
398              The  value must be a standard cursor name such as cross or @foo.
399              The internal form is a Tk_Cursor token like the ones returned by
400              Tk_AllocCursorFromObj.   This  option  type requires tkwin to be
401              supplied to procedures such as Tk_SetOptions, and when  the  op‐
402              tion is set the cursor for the window is changed by calling XDe‐
403              fineCursor.   This  option  type  also   supports   the   TK_OP‐
404              TION_NULL_OK flag.
405
406       TK_OPTION_CUSTOM
407              This option allows applications to define new option types.  The
408              clientData field of the entry points to a structure defining the
409              new  option type.  See the section CUSTOM OPTION TYPES below for
410              details.
411
412       TK_OPTION_DOUBLE
413              The string value must be a floating-point number in  the  format
414              accepted  by  strtol.   The  internal  form is a C double value.
415              This option type supports the TK_OPTION_NULL_OK flag; if a  NULL
416              value is set, the internal representation is set to zero.
417
418       TK_OPTION_END
419              Marks  the  end  of the template.  There must be a Tk_OptionSpec
420              structure with type TK_OPTION_END at the end of  each  template.
421              If  the  clientData field of this structure is not NULL, then it
422              points to an additional array of Tk_OptionSpec's, which  is  it‐
423              self  terminated  by another TK_OPTION_END entry.  Templates may
424              be chained arbitrarily deeply.  This feature allows  common  op‐
425              tions to be shared by several widget classes.
426
427       TK_OPTION_FONT
428              The  value  must  be a standard font name such as Times 16.  The
429              internal form is a Tk_Font handle  like  the  ones  returned  by
430              Tk_AllocFontFromObj.  This option type requires tkwin to be sup‐
431              plied to procedures such as Tk_SetOptions, and it  supports  the
432              TK_OPTION_NULL_OK flag.
433
434       TK_OPTION_INT
435              The  string  value  must be an integer in the format accepted by
436              strtol (e.g. 0 and 0x prefixes may be used to specify  octal  or
437              hexadecimal  numbers,  respectively).   The internal form is a C
438              int value.
439
440       TK_OPTION_JUSTIFY
441              The value must be a standard justification value such  as  left.
442              The  internal  form  is a Tk_Justify like the values returned by
443              Tk_GetJustifyFromObj.
444
445       TK_OPTION_PIXELS
446              The value must specify a screen distance such as 2i or 6.4.  The
447              internal  form  is an integer value giving a distance in pixels,
448              like the values returned by Tk_GetPixelsFromObj.  Note:  if  the
449              objOffset  field is not used then information about the original
450              value of this option will be lost.   See  OBJOFFSET  VS.  INTER‐
451              NALOFFSET  below  for  details.   This  option type supports the
452              TK_OPTION_NULL_OK flag; if a NULL value  is  set,  the  internal
453              representation is set to zero.
454
455       TK_OPTION_RELIEF
456              The  value must be standard relief such as raised.  The internal
457              form is an integer relief value such as TK_RELIEF_RAISED.   This
458              option  type  supports  the TK_OPTION_NULL_OK flag; if the empty
459              string is specified as the value for the option, the integer re‐
460              lief value is set to TK_RELIEF_NULL.
461
462       TK_OPTION_STRING
463              The  value  may  be any string.  The internal form is a (char *)
464              pointer that points to  a  dynamically  allocated  copy  of  the
465              value.  This option type supports the TK_OPTION_NULL_OK flag.
466
467       TK_OPTION_STRING_TABLE
468              For  this  type,  clientData is a pointer to an array of strings
469              suitable for passing to Tcl_GetIndexFromObj.  The value must  be
470              one of the strings in the table, or a unique abbreviation of one
471              of the strings.  The internal form is an integer giving the  in‐
472              dex into the table of the matching string, like the return value
473              from Tcl_GetStringFromObj.  This option type supports the TK_OP‐
474              TION_NULL_OK  flag;  if a NULL value is set, the internal repre‐
475              sentation is set to -1.
476
477       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
484       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

STORAGE MANAGEMENT ISSUES

492       If a field of a widget record has its offset stored in the objOffset or
493       internalOffset  field  of a Tk_OptionSpec structure then the procedures
494       described here will handle all of the storage allocation  and  resource
495       management  issues associated with the field.  When the value of an op‐
496       tion is changed, Tk_SetOptions (or Tk_FreeSavedOptions) will  automati‐
497       cally  free  any  resources  associated  with  the  old  value, such as
498       Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for
499       TK_OPTION_STRING  options.  For an option stored as an object using the
500       objOffset field of a Tk_OptionSpec, the widget record shares the object
501       pointed  to by the objv value from the call to Tk_SetOptions.  The ref‐
502       erence count for this object is incremented when a  pointer  to  it  is
503       stored  in  the  widget record and decremented when the option is modi‐
504       fied.  When the widget is deleted Tk_FreeConfigOptions  should  be  in‐
505       voked;  it  will  free  the  resources  associated with all options and
506       decrement reference counts for any objects.
507
508       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

OBJOFFSET VS. INTERNALOFFSET

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
535       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

CUSTOM OPTION TYPES

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
556              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
566              typedef Tcl_Obj *Tk_CustomOptionGetProc(
567                  ClientData clientData,
568                  Tk_Window tkwin,
569                  char *recordPtr,
570                  int internalOffset);
571
572              typedef void Tk_CustomOptionRestoreProc(
573                  ClientData clientData,
574                  Tk_Window tkwin,
575                  char *internalPtr,
576                  char *saveInternalPtr);
577
578              typedef void Tk_CustomOptionFreeProc(
579                  ClientData clientData,
580                  Tk_Window tkwin,
581                  char *internalPtr);
582
583       The Tk_ObjCustomOption structure contains six fields: a  name  for  the
584       custom  option  type; pointers to the four procedures; and a clientData
585       value to be passed to those procedures  when  they  are  invoked.   The
586       clientData value typically points to a structure containing information
587       that is needed by the procedures when they are parsing and printing op‐
588       tions.   RestoreProc and freeProc may be NULL, indicating that no func‐
589       tion should be called for those operations.
590
591       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
595              clientData
596                     A copy of the clientData field in the  Tk_ObjCustomOption
597                     structure.
598
599              interp A pointer to a Tcl interpreter, used for error reporting.
600
601              Tkwin  A copy of the tkwin argument to Tk_SetOptions
602
603              valuePtr
604                     A  pointer to a reference to a Tcl_Obj describing the new
605                     value for the option; it could have  been  specified  ex‐
606                     plicitly  in  the  call to Tk_SetOptions or it could come
607                     from the option database or a default.  If the  objOffset
608                     for  the  option  is  non-negative  (the  option value is
609                     stored as a  (Tcl_Obj  *)  in  the  widget  record),  the
610                     Tcl_Obj  pointer  referenced  by  valuePtr is the pointer
611                     that will be stored at  the  objOffset  for  the  option.
612                     SetProc  may  modify the value if necessary; for example,
613                     setProc may change the  value  to  NULL  to  support  the
614                     TK_OPTION_NULL_OK flag.
615
616              recordPtr
617                     A pointer to the start of the widget record to modify.
618
619              internalOffset
620                     Offset  in  bytes  from the start of the widget record to
621                     the location where the internal representation of the op‐
622                     tion value is to be placed.
623
624              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
632              flags  A copy of the flags field in the Tk_OptionSpec  structure
633                     for the option
634
635       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
640       The getProc procedure is invoked by Tk_GetOptionValue and Tk_GetOption‐
641       Info  to  retrieve a Tcl_Obj representation of the internal representa‐
642       tion of an option.  The clientData argument is a copy of the clientData
643       field  in the Tk_ObjCustomOption structure.  Tkwin is a copy of the tk‐
644       win argument to Tk_GetOptionValue or Tk_GetOptionInfo.  RecordPtr is  a
645       pointer to the beginning of the widget record to query.  InternalOffset
646       is the offset in bytes from the beginning of the widget record  to  the
647       location  where  the  internal  representation  of  the option value is
648       stored.  GetProc must return a pointer to a  Tcl_Obj  representing  the
649       value of the option.
650
651       The  restoreProc  procedure is invoked by Tk_RestoreSavedOptions to re‐
652       store a previously saved internal representation  of  a  custom  option
653       value.   The  clientData  argument is a copy of the clientData field in
654       the Tk_ObjCustomOption structure.  Tkwin is a copy of the  tkwin  argu‐
655       ment  to  Tk_GetOptionValue  or  Tk_GetOptionInfo.   InternalPtr  is  a
656       pointer to the location where internal  representation  of  the  option
657       value is stored.  SaveInternalPtr is a pointer to the saved value.  Re‐
658       storeProc must copy the value from saveInternalPtr  to  internalPtr  to
659       restore  the  value.   RestoreProc  need not free any memory associated
660       with either internalPtr or saveInternalPtr; freeProc will be invoked to
661       free that memory if necessary.  RestoreProc has no return value.
662
663       The  freeProc procedure is invoked by Tk_SetOptions and Tk_FreeSavedOp‐
664       tions to free any storage allocated for the internal representation  of
665       a  custom  option.  The clientData argument is a copy of the clientData
666       field in the Tk_ObjCustomOption structure.  Tkwin is a copy of the  tk‐
667       win  argument to Tk_GetOptionValue or Tk_GetOptionInfo.  InternalPtr is
668       a pointer to the location where the internal representation of the  op‐
669       tion  value  is  stored.  The freeProc must free any storage associated
670       with the option.  FreeProc has no return value.
671

KEYWORDS

673       anchor, bitmap, boolean, border, color, configuration  option,  cursor,
674       double,  font,  integer, justify, pixels, relief, screen distance, syn‐
675       onym
676
677
678
679Tk                                    8.1                     Tk_SetOptions(3)
Impressum