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
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
54       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
65       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
70       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
79       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
89       int objc (in)                               Number of values in objv.
90
91       Tcl_Obj *const objv[] (in)                  Command-line arguments  for
92                                                   setting         configuring
93                                                   options.
94
95       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
104       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
111       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
116       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
125       type name type (in)                         The name of the type  of  a
126                                                   record.
127
128       field name field (in)                       The  name  of  a  field  in
129                                                   records of type type.
130______________________________________________________________________________
131

DESCRIPTION

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
145       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
150       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
158       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
173       Tk_InitOptions is invoked when a new  widget  is  created  to  set  the
174       default  values  for  all of the widget's configuration options that do
175       not have TK_OPTION_DONT_SET_DEFAULT set in their flags field.   Tk_Ini‐
176       tOptions  is  passed  a  token  for an option table (optionTable) and a
177       pointer to a widget record (recordPtr), which is the C  structure  that
178       holds  information about this widget.  Tk_InitOptions uses the informa‐
179       tion in the option table to choose  an  appropriate  default  for  each
180       option,  except  those  having  TK_OPTION_DONT_SET_DEFAULT set, then it
181       stores the default value directly into the widget  record,  overwriting
182       any information that was already present in the widget record.  Tk_Ini‐
183       tOptions normally returns TCL_OK.  If an error occurred  while  setting
184       the  default  values (e.g., because a default value was erroneous) then
185       TCL_ERROR is returned and an error message is left in  interp's  result
186       if interp is not NULL.
187
188       Tk_SetOptions  is  invoked  to  modify  configuration  options based on
189       information specified in a Tcl command.  The command might be one  that
190       creates a new widget, or a command that modifies options on an existing
191       widget.  The objc and objv arguments describe the values of  the  argu‐
192       ments  from  the  Tcl  command.   Objv  must  contain an even number of
193       objects: the first object of each pair gives the name of an option  and
194       the  second  object gives the new value for that option.  Tk_SetOptions
195       looks up each name in optionTable, checks that the  new  value  of  the
196       option conforms to the type in optionTable, and stores the value of the
197       option into the widget record given by recordPtr.   Tk_SetOptions  nor‐
198       mally  returns TCL_OK.  If an error occurred (such as an unknown option
199       name or an illegal option value) then  TCL_ERROR  is  returned  and  an
200       error message is left in interp's result if interp is not NULL.
201
202       Tk_SetOptions has two additional features.  First, if the maskPtr argu‐
203       ment is not NULL then it points to an integer value that is  filled  in
204       with information about the options that were modified.  For each option
205       in the template passed to  Tk_CreateOptionTable  there  is  a  typeMask
206       field.   The bits of this field are defined by the code that implements
207       the widget; for example, each bit might correspond to a particular con‐
208       figuration  option.   Alternatively,  bits  might be used functionally.
209       For example, one bit might be used  for  redisplay:  all  options  that
210       affect the widget's display, such that changing the option requires the
211       widget to be redisplayed, might have that bit set.  Another  bit  might
212       indicate that the geometry of the widget must be recomputed, and so on.
213       Tk_SetOptions OR's together the typeMask fields from  all  the  options
214       that  were  modified and returns this value at *maskPtr; the caller can
215       then use this information to optimize itself so that, for  example,  it
216       does not redisplay the widget if the modified options do not affect the
217       widget's appearance.
218
219       The second additional feature of Tk_SetOptions has  to  do  with  error
220       recovery.   If  an error occurs while processing configuration options,
221       this feature makes it possible to restore all the configuration options
222       to  their  previous  values.   Errors can occur either while processing
223       options in Tk_SetOptions or later in the caller.   In  many  cases  the
224       caller  does  additional  processing  after  Tk_SetOptions returns; for
225       example, it might use an option value to set a trace on a variable  and
226       may  detect  an  error if the variable is an array instead of a scalar.
227       Error recovery is enabled by  passing  in  a  non-NULL  value  for  the
228       savePtr  argument  to  Tk_SetOptions;  this  should  be a pointer to an
229       uninitialized  Tk_SavedOptions  structure  on   the   caller's   stack.
230       Tk_SetOptions  overwrites  the  structure  pointed  to  by savePtr with
231       information about the old values of any options modified by the  proce‐
232       dure.   If  Tk_SetOptions  returns  successfully,  the  caller uses the
233       structure in one of two ways.  If the caller completes  its  processing
234       of  the new options without any errors, then it must pass the structure
235       to Tk_FreeSavedOptions so that the old values can  be  freed.   If  the
236       caller  detects  an error in its processing of the new options, then it
237       should pass the structure to Tk_RestoreSavedOptions,  which  will  copy
238       the old values back into the widget record and free the new values.  If
239       Tk_SetOptions detects an  error  then  it  automatically  restores  any
240       options  that had already been modified and leaves *savePtr in an empty
241       state:  the  caller  need  not  call  either   Tk_FreeSavedOptions   or
242       Tk_RestoreSavedOptions.   If  the  savePtr argument to Tk_SetOptions is
243       NULL then Tk_SetOptions frees each old option value immediately when it
244       sets  a  new value for the option.  In this case, if an error occurs in
245       the third option, the old values for the first two  options  cannot  be
246       restored.
247
248       Tk_GetOptionValue  returns  the current value of a configuration option
249       for a particular widget.  The namePtr argument contains the name of  an
250       option;  Tk_GetOptionValue  uses  optionTable  to lookup the option and
251       extract its value from the widget record pointed to by recordPtr,  then
252       it  returns an object containing that value.  If an error occurs (e.g.,
253       because namePtr contains an unknown option name) then NULL is  returned
254       and an error message is left in interp's result unless interp is NULL.
255
256       Tk_GetOptionInfo  returns  information about configuration options in a
257       form suitable for configure widget commands.  If the  namePtr  argument
258       is not NULL, it points to an object that gives the name of a configura‐
259       tion option; Tk_GetOptionInfo returns an object containing a list  with
260       five  elements,  which  are  the name of the option, the name and class
261       used for the option in the option database, the default value  for  the
262       option,  and the current value for the option.  If the namePtr argument
263       is NULL, then Tk_GetOptionInfo returns information about all options in
264       the  form  of a list of lists; each sublist describes one option.  Syn‐
265       onym options are handled differently depending on  whether  namePtr  is
266       NULL:  if  namePtr is NULL then the sublist for each synonym option has
267       only two elements, which are the name of the option and the name of the
268       other option that it refers to; if namePtr is non-NULL and names a syn‐
269       onym option then the object returned is the five-element list  for  the
270       other  option  that  the  synonym refers to.  If an error occurs (e.g.,
271       because namePtr contains an unknown option name) then NULL is  returned
272       and an error message is left in interp's result unless interp is NULL.
273
274       Tk_FreeConfigOptions  must  be  invoked  when  a widget is deleted.  It
275       frees all of the resources associated with  any  of  the  configuration
276       options defined in recordPtr by optionTable.
277
278       The Tk_Offset macro is provided as a safe way of generating the objOff‐
279       set and internalOffset values for entries in Tk_OptionSpec  structures.
280       It takes two arguments: the name of a type of record, and the name of a
281       field in that record. It returns the byte offset of the named field  in
282       records of the given type.
283

TEMPLATES

285       The  array  of  Tk_OptionSpec structures passed to Tk_CreateOptionTable
286       via its templatePtr argument describes the configuration  options  sup‐
287       ported  by a particular class of widgets.  Each structure specifies one
288       configuration option and has the following fields:
289              typedef struct {
290                  Tk_OptionType type;
291                  const char *optionName;
292                  const char *dbName;
293                  const char *dbClass;
294                  const char *defValue;
295                  int objOffset;
296                  int internalOffset;
297                  int flags;
298                  const void *clientData;
299                  int typeMask;
300              } Tk_OptionSpec;
301       The type field indicates what kind  of  configuration  option  this  is
302       (e.g.  TK_OPTION_COLOR for a color value, or TK_OPTION_INT for an inte‐
303       ger value).  Type determines how the value  of  the  option  is  parsed
304       (more  on  this below).  The optionName field is a string such as -font
305       or -bg; it is the name used for the option in Tcl commands  and  passed
306       to  procedures  via  the  objc  or  namePtr  arguments.  The dbName and
307       dbClass fields are used by Tk_InitOptions to look up  a  default  value
308       for  this  option  in  the  option database; if dbName is NULL then the
309       option database is not used by Tk_InitOptions  for  this  option.   The
310       defValue  field specifies a default value for this configuration option
311       if no value is specified in the option  database.   The  objOffset  and
312       internalOffset  fields indicate where to store the value of this option
313       in widget records (more on this below); values for  the  objOffset  and
314       internalOffset  fields  should  always  be generated with the Tk_Offset
315       macro.  The flags field contains additional information to control  the
316       processing  of  this  configuration  option  (see  below  for details).
317       ClientData provides additional type-specific  data  needed  by  certain
318       types.  For instance, for TK_OPTION_COLOR types, clientData is a string
319       giving the default value  to  use  on  monochrome  displays.   See  the
320       descriptions of the different types below for details.  The last field,
321       typeMask, is used by Tk_SetOptions to return  information  about  which
322       options  were  modified; see the description of Tk_SetOptions above for
323       details.
324
325       When Tk_InitOptions and Tk_SetOptions store the value of an option into
326       the  widget  record,  they  can  do  it  in either of two ways.  If the
327       objOffset field of the Tk_OptionSpec is greater than or equal to  zero,
328       then the value of the option is stored as a (Tcl_Obj *) at the location
329       in the widget record given by objOffset.  If the  internalOffset  field
330       of  the  Tk_OptionSpec is greater than or equal to zero, then the value
331       of the option is stored in a type-specific internal form at  the  loca‐
332       tion in the widget record given by internalOffset.  For example, if the
333       option's type is TK_OPTION_INT then the internal form  is  an  integer.
334       If  the objOffset or internalOffset field is negative then the value is
335       not stored in that form.  At least one of the offsets must  be  greater
336       than or equal to zero.
337
338       The flags field consists of one or more bits ORed together. The follow‐
339       ing flags are supported:
340
341       TK_OPTION_NULL_OK
342              If this bit is set for an option then an empty  string  will  be
343              accepted  as the value for the option and the resulting internal
344              form will be a NULL pointer, a zero value, or None, depending on
345              the  type  of  the  option.   If  the flag is not set then empty
346              strings will result in errors.  TK_OPTION_NULL_OK  is  typically
347              used  to  allow  a feature to be turned off entirely, e.g. set a
348              cursor value to None so that a window simply inherits  its  par‐
349              ent's    cursor.     Not    all   option   types   support   the
350              TK_OPTION_NULL_OK flag; for those that do, there is an  explicit
351              indication of that fact in the descriptions below.
352
353       TK_OPTION_DONT_SET_DEFAULT
354              If  this  bit is set for an option then no default value will be
355              set in Tk_InitOptions for this option. Neither the option  data‐
356              base,  nor any system default value, nor optionTable are used to
357              give a default value to this option. Instead it is assumed  that
358              the  caller  has  already supplied a default value in the widget
359              code.
360
361       The type field of each Tk_OptionSpec structure determines how to  parse
362       the  value  of that configuration option. The legal value for type, and
363       the corresponding actions, are described below.  If the type requires a
364       tkwin  value  to be passed into procedures like Tk_SetOptions, or if it
365       uses the clientData field of the Tk_OptionSpec, then  it  is  indicated
366       explicitly;  if  not  mentioned,  the  type  requires neither tkwin nor
367       clientData.
368
369       TK_OPTION_ANCHOR
370              The value must be a standard anchor position such as ne or  cen‐
371              ter.   The  internal  form  is  a  Tk_Anchor value like the ones
372              returned by Tk_GetAnchorFromObj.
373
374       TK_OPTION_BITMAP
375              The value must be a standard Tk bitmap name. The  internal  form
376              is  a  Pixmap token like the ones returned by Tk_AllocBitmapFro‐
377              mObj.  This option type requires tkwin to be supplied to  proce‐
378              dures    such    as   Tk_SetOptions,   and   it   supports   the
379              TK_OPTION_NULL_OK flag.
380
381       TK_OPTION_BOOLEAN
382              The value must be a standard boolean value such as true  or  no.
383              The internal form is an integer with value 0 or 1.
384
385       TK_OPTION_BORDER
386              The  value must be a standard color name such as red or #ff8080.
387              The internal form is a Tk_3DBorder token like the ones  returned
388              by  Tk_Alloc3DBorderFromObj.  This option type requires tkwin to
389              be supplied to procedures such as Tk_SetOptions, and it supports
390              the TK_OPTION_NULL_OK flag.
391
392       TK_OPTION_COLOR
393              The  value must be a standard color name such as red or #ff8080.
394              The internal form is an (XColor *) token like the ones  returned
395              by  Tk_AllocColorFromObj.  This option type requires tkwin to be
396              supplied to procedures such as Tk_SetOptions,  and  it  supports
397              the TK_OPTION_NULL_OK flag.
398
399       TK_OPTION_CURSOR
400              The  value must be a standard cursor name such as cross or @foo.
401              The internal form is a Tk_Cursor token like the ones returned by
402              Tk_AllocCursorFromObj.   This  option  type requires tkwin to be
403              supplied to procedures  such  as  Tk_SetOptions,  and  when  the
404              option  is  set  the cursor for the window is changed by calling
405              XDefineCursor.    This   option   type   also    supports    the
406              TK_OPTION_NULL_OK flag.
407
408       TK_OPTION_CUSTOM
409              This option allows applications to define new option types.  The
410              clientData field of the entry points to a structure defining the
411              new  option type.  See the section CUSTOM OPTION TYPES below for
412              details.
413
414       TK_OPTION_DOUBLE
415              The string value must be a floating-point number in  the  format
416              accepted  by  strtol.   The  internal  form is a C double value.
417              This option type supports the TK_OPTION_NULL_OK flag; if a  NULL
418              value is set, the internal representation is set to zero.
419
420       TK_OPTION_END
421              Marks  the  end  of the template.  There must be a Tk_OptionSpec
422              structure with type TK_OPTION_END at the end of  each  template.
423              If  the  clientData field of this structure is not NULL, then it
424              points to an  additional  array  of  Tk_OptionSpec's,  which  is
425              itself terminated by another TK_OPTION_END entry.  Templates may
426              be chained  arbitrarily  deeply.   This  feature  allows  common
427              options to be shared by several widget classes.
428
429       TK_OPTION_FONT
430              The  value  must  be a standard font name such as Times 16.  The
431              internal form is a Tk_Font handle  like  the  ones  returned  by
432              Tk_AllocFontFromObj.  This option type requires tkwin to be sup‐
433              plied to procedures such as Tk_SetOptions, and it  supports  the
434              TK_OPTION_NULL_OK flag.
435
436       TK_OPTION_INT
437              The  string  value  must be an integer in the format accepted by
438              strtol (e.g. 0 and 0x prefixes may be used to specify  octal  or
439              hexadecimal  numbers,  respectively).   The internal form is a C
440              int value.
441
442       TK_OPTION_JUSTIFY
443              The value must be a standard justification value such  as  left.
444              The  internal  form  is a Tk_Justify like the values returned by
445              Tk_GetJustifyFromObj.
446
447       TK_OPTION_PIXELS
448              The value must specify a screen distance such as 2i or 6.4.  The
449              internal  form  is an integer value giving a distance in pixels,
450              like the values returned by Tk_GetPixelsFromObj.  Note:  if  the
451              objOffset  field is not used then information about the original
452              value of this option will be lost.   See  OBJOFFSET  VS.  INTER‐
453              NALOFFSET  below  for  details.   This  option type supports the
454              TK_OPTION_NULL_OK flag; if a NULL value  is  set,  the  internal
455              representation is set to zero.
456
457       TK_OPTION_RELIEF
458              The  value must be standard relief such as raised.  The internal
459              form is an integer relief value such as TK_RELIEF_RAISED.   This
460              option  type  supports  the TK_OPTION_NULL_OK flag; if the empty
461              string is specified as the value for  the  option,  the  integer
462              relief value is set to TK_RELIEF_NULL.
463
464       TK_OPTION_STRING
465              The  value  may  be any string.  The internal form is a (char *)
466              pointer that points to  a  dynamically  allocated  copy  of  the
467              value.  This option type supports the TK_OPTION_NULL_OK flag.
468
469       TK_OPTION_STRING_TABLE
470              For  this  type,  clientData is a pointer to an array of strings
471              suitable for passing to Tcl_GetIndexFromObj.  The value must  be
472              one of the strings in the table, or a unique abbreviation of one
473              of the strings.  The internal form  is  an  integer  giving  the
474              index  into  the  table  of the matching string, like the return
475              value from Tcl_GetStringFromObj.
476
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
496       option is changed, Tk_SetOptions (or Tk_FreeSavedOptions) will automat‐
497       ically  free  any  resources  associated  with  the  old value, such as
498       Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for
499       TK_OPTION_STRING  options.  For an option stored as an object using the
500       objOffset field of a Tk_OptionSpec, the widget record shares the object
501       pointed  to by the objv value from the call to Tk_SetOptions.  The ref‐
502       erence count for this object is incremented when a  pointer  to  it  is
503       stored  in  the  widget record and decremented when the option is modi‐
504       fied.  When  the  widget  is  deleted  Tk_FreeConfigOptions  should  be
505       invoked;  it  will  free  the resources associated with all options and
506       decrement reference counts for any objects.
507
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
588       options.   RestoreProc  and  freeProc  may  be NULL, indicating that no
589       function 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
606                     explicitly  in the call to Tk_SetOptions or it could come
607                     from the option database or a default.  If the  objOffset
608                     for  the  option  is  non-negative  (the  option value is
609                     stored as a  (Tcl_Obj  *)  in  the  widget  record),  the
610                     Tcl_Obj  pointer  referenced  by  valuePtr is the pointer
611                     that will be stored at  the  objOffset  for  the  option.
612                     SetProc  may  modify the value if necessary; for example,
613                     setProc may change the  value  to  NULL  to  support  the
614                     TK_OPTION_NULL_OK flag.
615
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
622                     option 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
644       tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo.  RecordPtr  is
645       a pointer to the beginning of the widget record to query.  InternalOff‐
646       set is the offset in bytes from the beginning of the widget  record  to
647       the  location  where the internal representation of the option value is
648       stored.  GetProc must return a pointer to a  Tcl_Obj  representing  the
649       value of the option.
650
651       The  restoreProc  procedure  is  invoked  by  Tk_RestoreSavedOptions to
652       restore a previously saved internal representation of a  custom  option
653       value.   The  clientData  argument is a copy of the clientData field in
654       the Tk_ObjCustomOption structure.  Tkwin is a copy of the  tkwin  argu‐
655       ment  to  Tk_GetOptionValue  or  Tk_GetOptionInfo.   InternalPtr  is  a
656       pointer to the location where internal  representation  of  the  option
657       value  is  stored.   SaveInternalPtr  is  a pointer to the saved value.
658       RestoreProc must copy the value from saveInternalPtr to internalPtr  to
659       restore  the  value.   RestoreProc  need not free any memory associated
660       with either internalPtr or saveInternalPtr; freeProc will be invoked to
661       free that memory if necessary.  RestoreProc has no return value.
662
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
667       tkwin  argument  to Tk_GetOptionValue or Tk_GetOptionInfo.  InternalPtr
668       is a pointer to the location where the internal representation  of  the
669       option  value is stored.  The freeProc must free any storage associated
670       with the option.  FreeProc has no return value.
671

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