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.  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
186       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
200       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
217       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
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
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
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.,
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
272       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
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                  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
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
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
336       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
348       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
356       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
361       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
368       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
372       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
379       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
386       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
395       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
401       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
407       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
416       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
423       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
429       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
434       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
444       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
451       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
456       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
464       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
471       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

STORAGE MANAGEMENT ISSUES

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

OBJOFFSET VS. INTERNALOFFSET

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

CUSTOM OPTION TYPES

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
543              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
553              typedef Tcl_Obj *Tk_CustomOptionGetProc(
554                  ClientData clientData,
555                  Tk_Window tkwin,
556                  char *recordPtr,
557                  int internalOffset);
558
559              typedef void Tk_CustomOptionRestoreProc(
560                  ClientData clientData,
561                  Tk_Window tkwin,
562                  char *internalPtr,
563                  char *saveInternalPtr);
564
565              typedef void Tk_CustomOptionFreeProc(
566                  ClientData clientData,
567                  Tk_Window tkwin,
568                  char *internalPtr);
569
570       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
578       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
582              clientData
583                     A  copy of the clientData field in the Tk_ObjCustomOption
584                     structure.
585
586              interp A pointer to a Tcl interpreter, used for error reporting.
587
588              Tkwin  A copy of the tkwin argument to Tk_SetOptions
589
590              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
603              recordPtr
604                     A pointer to the start of the widget record to modify.
605
606              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
611              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
619              flags  A  copy of the flags field in the Tk_OptionSpec structure
620                     for the option
621
622       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
627       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
638       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
650       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

KEYWORDS

660       anchor,  bitmap,  boolean, border, color, configuration option, cursor,
661       double, font, integer, justify, pixels, relief, screen  distance,  syn‐
662       onym
663
664
665
666Tk                                    8.1                     Tk_SetOptions(3)
Impressum