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

NAME

8       Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions
9       - process configuration options for widgets
10

SYNOPSIS

12       #include <tk.h>
13
14       int
15       Tk_ConfigureWidget(interp, tkwin, specs, argc, argv, widgRec, flags)
16
17       int
18       Tk_ConfigureInfo(interp, tkwin, specs, widgRec, argvName, flags)
19
20       int
21       Tk_ConfigureValue(interp, tkwin, specs, widgRec, argvName, flags)
22
23       Tk_FreeOptions(specs, widgRec, display, flags)
24

ARGUMENTS

26       Tcl_Interp *interp (in)     Interpreter to use for returning error mes‐
27                                   sages.
28
29       Tk_Window tkwin (in)        Window  used to represent widget (needed to
30                                   set up X resources).
31
32       const Tk_ConfigSpec *specs (in)
33                                   Pointer to table specifying legal  configu‐
34                                   ration options for this widget.
35
36       int argc (in)               Number of arguments in argv.
37
38       const char **argv (in)      Command-line  options  for configuring wid‐
39                                   get.
40
41       char *widgRec (in/out)      Points to widget record structure.   Fields
42                                   in  this  structure get modified by Tk_Con‐
43                                   figureWidget to hold configuration informa‐
44                                   tion.
45
46       int flags (in)              If  non-zero,  then  it  specifies an OR-ed
47                                   combination of flags that control the  pro‐
48                                   cessing   of   configuration   information.
49                                   TK_CONFIG_ARGV_ONLY causes the option data‐
50                                   base  and  defaults to be ignored, and flag
51                                   bits TK_CONFIG_USER_BIT and higher are used
52                                   to selectively disable entries in specs.
53
54       type name type (in)         The name of the type of a widget record.
55
56       field name field (in)       The  name  of  a  field  in records of type
57                                   type.
58
59       const char *argvName (in)   The name used on Tcl command lines to refer
60                                   to  a particular option (e.g. when creating
61                                   a widget or invoking the  configure  widget
62                                   command).  If non-NULL, then information is
63                                   returned only for this  option.   If  NULL,
64                                   then information is returned for all avail‐
65                                   able options.
66
67       Display *display (in)       Display containing widget whose  record  is
68                                   being  freed;   needed  in order to free up
69                                   resources.
70______________________________________________________________________________
71

DESCRIPTION

73       Note: Tk_ConfigureWidget should be replaced with the new Tcl_Obj  based
74       API Tk_SetOptions.  The old interface is retained for backward compati‐
75       bility.
76
77       Tk_ConfigureWidget is called to configure various aspects of a  widget,
78       such  as  colors, fonts, border width, etc.  It is intended as a conve‐
79       nience procedure to reduce the amount of code that must be  written  in
80       individual  widget managers to handle configuration information.  It is
81       typically invoked when widgets are created, and again when the  config‐
82       ure  command  is invoked for a widget.  Although intended primarily for
83       widgets, Tk_ConfigureWidget can be used in other situations where argc-
84       argv  information  is to be used to fill in a record structure, such as
85       configuring graphical elements for a canvas  widget  or  entries  of  a
86       menu.
87
88       Tk_ConfigureWidget  processes  a  table  specifying  the  configuration
89       options that are supported (specs) and  a  collection  of  command-line
90       arguments  (argc and argv) to fill in fields of a record (widgRec).  It
91       uses the option database and defaults specified in  specs  to  fill  in
92       fields  of  widgRec that are not specified in argv.  Tk_ConfigureWidget
93       normally returns the value TCL_OK; in this  case  it  does  not  modify
94       interp.   If  an error occurs then TCL_ERROR is returned and Tk_Config‐
95       ureWidget will leave an error message in interpreter interp's result in
96       the standard Tcl fashion.  In the event of an error return, some of the
97       fields of widgRec could already have been set, if configuration  infor‐
98       mation  for  them was successfully processed before the error occurred.
99       The other fields will be set  to  reasonable  initial  values  so  that
100       Tk_FreeOptions can be called for cleanup.
101
102       The  specs  array specifies the kinds of configuration options expected
103       by the widget.  Each of its entries specifies one configuration  option
104       and has the following structure:
105              typedef struct {
106                  int type;
107                  const char *argvName;
108                  const char *dbName;
109                  const char *dbClass;
110                  const char *defValue;
111                  int offset;
112                  int specFlags;
113                  const Tk_CustomOption *customPtr;
114              } Tk_ConfigSpec;
115       The  type  field  indicates  what  type of configuration option this is
116       (e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for an  inte‐
117       ger  value).   The  type  field  indicates  how to use the value of the
118       option (more on this below).  The argvName field is a  string  such  as
119       “-font”  or  “-bg”, which is compared with the values in argv (if argv‐
120       Name is NULL it means this is a grouped  entry;   see  GROUPED  ENTRIES
121       below).   The dbName and dbClass fields are used to look up a value for
122       this option in the option database.  The  defValue  field  specifies  a
123       default value for this configuration option if no value is specified in
124       either argv or the option database.  Offset indicates where in  widgRec
125       to  store  information  about this option, and specFlags contains addi‐
126       tional information to control  the  processing  of  this  configuration
127       option  (see  FLAGS below).  The last field, customPtr, is only used if
128       type is TK_CONFIG_CUSTOM;  see CUSTOM OPTION TYPES below.
129
130       Tk_ConfigureWidget first processes argv to see which (if any)  configu‐
131       ration  options  are specified there.  Argv must contain an even number
132       of fields;  the first of each pair of fields must match the argvName of
133       some entry in specs (unique abbreviations are acceptable), and the sec‐
134       ond field of the pair contains the value for that configuration option.
135       If  there  are entries in spec for which there were no matching entries
136       in argv, Tk_ConfigureWidget uses the dbName and dbClass fields  of  the
137       specs entry to probe the option database;  if a value is found, then it
138       is used as the value for the option.  Finally, if no entry is found  in
139       the  option  database, the defValue field of the specs entry is used as
140       the value for the configuration option.  If the defValue is NULL, or if
141       the  TK_CONFIG_DONT_SET_DEFAULT  bit  is set in flags, then there is no
142       default value and this specs entry will be ignored if no value is spec‐
143       ified in argv or the option database.
144
145       Once  a  string  value  has been determined for a configuration option,
146       Tk_ConfigureWidget translates the string value into a more useful form,
147       such  as  a  color  if type is TK_CONFIG_COLOR or an integer if type is
148       TK_CONFIG_INT.  This value is then stored in the record pointed  to  by
149       widgRec.  This record is assumed to contain information relevant to the
150       manager of the widget;  its exact type is unknown  to  Tk_ConfigureWid‐
151       get.   The  offset field of each specs entry indicates where in widgRec
152       to store the information about this configuration option.   You  should
153       use  the  Tk_Offset  macro  to  generate offset values (see below for a
154       description of Tk_Offset).  The location indicated by widgRec and  off‐
155       set will be referred to as the “target” in the descriptions below.
156
157       The  type  field  of each entry in specs determines what to do with the
158       string value of that configuration option.  The legal values for  type,
159       and the corresponding actions, are:
160
161       TK_CONFIG_ACTIVE_CURSOR
162              The value must be an ASCII string identifying a cursor in a form
163              suitable for passing to Tk_GetCursor.  The value is converted to
164              a  Tk_Cursor by calling Tk_GetCursor and the result is stored in
165              the target.  In addition,  the  resulting  cursor  is  made  the
166              active  cursor  for  tkwin by calling XDefineCursor.  If TK_CON‐
167              FIG_NULL_OK is specified in specFlags then the value may  be  an
168              empty string, in which case the target and tkwin's active cursor
169              will be set to None.  If the previous value of  the  target  was
170              not None, then it is freed by passing it to Tk_FreeCursor.
171
172       TK_CONFIG_ANCHOR
173              The value must be an ASCII string identifying an anchor point in
174              one of the ways accepted by Tk_GetAnchor.  The  string  is  con‐
175              verted  to a Tk_Anchor by calling Tk_GetAnchor and the result is
176              stored in the target.
177
178       TK_CONFIG_BITMAP
179              The value must be an ASCII string identifying a bitmap in a form
180              suitable for passing to Tk_GetBitmap.  The value is converted to
181              a Pixmap by calling Tk_GetBitmap and the result is stored in the
182              target.  If TK_CONFIG_NULL_OK is specified in specFlags then the
183              value may be an empty string, in which case the target is set to
184              None.  If the previous value of the target was not None, then it
185              is freed by passing it to Tk_FreeBitmap.
186
187       TK_CONFIG_BOOLEAN
188              The value must be an ASCII string specifying  a  boolean  value.
189              Any  of  the values “true”, “yes”, “on”, or “1”, or an abbrevia‐
190              tion of one of these values,  means  true;  any  of  the  values
191              “false”, “no”, “off”, or “0”, or an abbreviation of one of these
192              values, means false.  The target is expected to be  an  integer;
193              for true values it will be set to 1 and for false values it will
194              be set to 0.
195
196       TK_CONFIG_BORDER
197              The value must be an ASCII string identifying a border color  in
198              a  form  suitable  for  passing to Tk_Get3DBorder.  The value is
199              converted to a (Tk_3DBorder *) by calling Tk_Get3DBorder and the
200              result  is stored in the target.  If TK_CONFIG_NULL_OK is speci‐
201              fied in specFlags then the value may  be  an  empty  string,  in
202              which  case  the  target  will  be set to NULL.  If the previous
203              value of the target was not NULL, then it is freed by passing it
204              to Tk_Free3DBorder.
205
206       TK_CONFIG_CAP_STYLE
207              The value must be an ASCII string identifying a cap style in one
208              of the ways accepted by Tk_GetCapStyle.  The string is converted
209              to  an  integer  value corresponding to the cap style by calling
210              Tk_GetCapStyle and the result is stored in the target.
211
212       TK_CONFIG_COLOR
213              The value must be an ASCII string identifying a color in a  form
214              suitable  for passing to Tk_GetColor.  The value is converted to
215              an (XColor *) by calling Tk_GetColor and the result is stored in
216              the target.  If TK_CONFIG_NULL_OK is specified in specFlags then
217              the value may be an empty string, in which case the target  will
218              be  set  to  None.   If the previous value of the target was not
219              NULL, then it is freed by passing it to Tk_FreeColor.
220
221       TK_CONFIG_CURSOR
222              This option is identical to TK_CONFIG_ACTIVE_CURSOR except  that
223              the new cursor is not made the active one for tkwin.
224
225       TK_CONFIG_CUSTOM
226              This option allows applications to define new option types.  The
227              customPtr field of the entry points to a structure defining  the
228              new  option type.  See the section CUSTOM OPTION TYPES below for
229              details.
230
231       TK_CONFIG_DOUBLE
232              The value must be an ASCII floating-point number in  the  format
233              accepted  by strtol.  The string is converted to a double value,
234              and the value is stored in the target.
235
236       TK_CONFIG_END
237              Marks the end of the table.  The last entry in specs  must  have
238              this  type;   all  of  its  other fields are ignored and it will
239              never match any arguments.
240
241       TK_CONFIG_FONT
242              The value must be an ASCII string identifying a font in  a  form
243              suitable for passing to Tk_GetFont.  The value is converted to a
244              Tk_Font by calling Tk_GetFont and the result is  stored  in  the
245              target.  If TK_CONFIG_NULL_OK is specified in specFlags then the
246              value may be an empty string, in which case the target  will  be
247              set  to NULL.  If the previous value of the target was not NULL,
248              then it is freed by passing it to Tk_FreeFont.
249
250       TK_CONFIG_INT
251              The value must be an ASCII integer string in the format accepted
252              by  strtol  (e.g.   “0” and “0x” prefixes may be used to specify
253              octal or hexadecimal numbers, respectively).  The string is con‐
254              verted to an integer value and the integer is stored in the tar‐
255              get.
256
257       TK_CONFIG_JOIN_STYLE
258              The value must be an ASCII string identifying a  join  style  in
259              one of the ways accepted by Tk_GetJoinStyle.  The string is con‐
260              verted to an integer value corresponding to the  join  style  by
261              calling Tk_GetJoinStyle and the result is stored in the target.
262
263       TK_CONFIG_JUSTIFY
264              The  value  must  be an ASCII string identifying a justification
265              method in one of the ways accepted by Tk_GetJustify.  The string
266              is  converted  to  a Tk_Justify by calling Tk_GetJustify and the
267              result is stored in the target.
268
269       TK_CONFIG_MM
270              The value must specify a screen distance in  one  of  the  forms
271              acceptable  to  Tk_GetScreenMM.  The string is converted to dou‐
272              ble-precision floating-point distance  in  millimeters  and  the
273              value is stored in the target.
274
275       TK_CONFIG_PIXELS
276              The  value must specify screen units in one of the forms accept‐
277              able to Tk_GetPixels.  The string is  converted  to  an  integer
278              distance in pixels and the value is stored in the target.
279
280       TK_CONFIG_RELIEF
281              The value must be an ASCII string identifying a relief in a form
282              suitable for passing to Tk_GetRelief.  The value is converted to
283              an  integer  relief value by calling Tk_GetRelief and the result
284              is stored in the target.
285
286       TK_CONFIG_STRING
287              A copy of the value is made  by  allocating  memory  space  with
288              Tcl_Alloc  and  copying the value into the dynamically-allocated
289              space.  A pointer to the new string is stored in the target.  If
290              TK_CONFIG_NULL_OK  is  specified in specFlags then the value may
291              be an empty string, in which case the  target  will  be  set  to
292              NULL.  If the previous value of the target was not NULL, then it
293              is freed by passing it to Tcl_Free.
294
295       TK_CONFIG_SYNONYM
296              This type value identifies special entries  in  specs  that  are
297              synonyms  for other entries.  If an argv value matches the argv‐
298              Name of  a  TK_CONFIG_SYNONYM  entry,  the  entry  is  not  used
299              directly. Instead, Tk_ConfigureWidget searches specs for another
300              entry whose argvName is the same as  the  dbName  field  in  the
301              TK_CONFIG_SYNONYM  entry;  this new entry is used just as if its
302              argvName had matched the  argv  value.   The  synonym  mechanism
303              allows  multiple  argv values to be used for a single configura‐
304              tion option, such as “-background” and “-bg”.
305
306       TK_CONFIG_UID
307              The  value  is  translated  to  a  Tk_Uid  (by  passing  it   to
308              Tk_GetUid).   The  resulting  value is stored in the target.  If
309              TK_CONFIG_NULL_OK is specified in specFlags and the value is  an
310              empty string then the target will be set to NULL.
311
312       TK_CONFIG_WINDOW
313              The  value  must  be  a window path name.  It is translated to a
314              Tk_Window token and the token is stored in the target.
315

GROUPED ENTRIES

317       In some cases it is useful to generate multiple resources from a single
318       configuration  value.   For example, a color name might be used both to
319       generate the background color for a widget (using TK_CONFIG_COLOR)  and
320       to  generate  a  3-D  border  to  draw around the widget (using TK_CON‐
321       FIG_BORDER).  In cases like this it is possible to specify that several
322       consecutive  entries  in specs are to be treated as a group.  The first
323       entry is used  to  determine  a  value  (using  its  argvName,  dbName,
324       dbClass,  and  defValue  fields).   The value will be processed several
325       times (one for each entry in the group), generating multiple  different
326       resources  and  modifying multiple targets within widgRec.  Each of the
327       entries after the first must have a NULL value in its  argvName  field;
328       this indicates that the entry is to be grouped with the entry that pre‐
329       cedes it.  Only the type and offset fields are used from these  follow-
330       on entries.
331

FLAGS

333       The  flags argument passed to Tk_ConfigureWidget is used in conjunction
334       with the specFlags fields in the entries of specs to provide additional
335       control over the processing of configuration options.  These values are
336       used in three different ways as described below.
337
338       First, if the flags argument  to  Tk_ConfigureWidget  has  the  TK_CON‐
339       FIG_ARGV_ONLY  bit  set  (i.e., flags | TK_CONFIG_ARGV_ONLY != 0), then
340       the option database and defValue fields are not used.  In this case, if
341       an  entry in specs does not match a field in argv then nothing happens:
342       the corresponding target is not modified.  This feature is useful  when
343       the  goal is to modify certain configuration options while leaving oth‐
344       ers in their current state, such as when a configure widget command  is
345       being processed.
346
347       Second, the specFlags field of an entry in specs may be used to control
348       the processing of that entry.  Each specFlags field may consists of  an
349       OR-ed combination of the following values:
350
351       TK_CONFIG_COLOR_ONLY
352              If this bit is set then the entry will only be considered if the
353              display for tkwin has more than one bit plane.  If  the  display
354              is monochromatic then this specs entry will be ignored.
355
356       TK_CONFIG_MONO_ONLY
357              If this bit is set then the entry will only be considered if the
358              display for tkwin has exactly one bit plane.  If the display  is
359              not monochromatic then this specs entry will be ignored.
360
361       TK_CONFIG_NULL_OK
362              This  bit  is  only  relevant for some types of entries (see the
363              descriptions of the various entry types above).  If this bit  is
364              set,  it  indicates  that an empty string value for the field is
365              acceptable and if it occurs then the target  should  be  set  to
366              NULL or None, depending on the type of the target.  This flag is
367              typically used to allow a feature to  be  turned  off  entirely,
368              e.g. set a cursor value to None so that a window simply inherits
369              its parent's cursor.  If this bit is not set then empty  strings
370              are processed as strings, which generally results in an error.
371
372       TK_CONFIG_DONT_SET_DEFAULT
373              If  this  bit  is  one,  it means that the defValue field of the
374              entry should only be used for returning  the  default  value  in
375              Tk_ConfigureInfo.   In  calls  to  Tk_ConfigureWidget no default
376              will be supplied for entries with this flag set;  it is  assumed
377              that the caller has already supplied a default value in the tar‐
378              get location.  This flag  provides  a  performance  optimization
379              where it is expensive to process the default string:  the client
380              can compute the default once, save the  value,  and  provide  it
381              before calling Tk_ConfigureWidget.
382
383       TK_CONFIG_OPTION_SPECIFIED
384              This bit is deprecated. It used to be set and cleared by Tk_Con‐
385              figureWidget so that callers  could  detect  what  entries  were
386              specified  in argv, but it was removed because it was inherently
387              thread-unsafe. Code that wishes  to  detect  what  options  were
388              specified should use Tk_SetOptions instead.
389
390       The  TK_CONFIG_MONO_ONLY  and  TK_CONFIG_COLOR_ONLY flags are typically
391       used to specify different default values for monochrome and color  dis‐
392       plays.   This is done by creating two entries in specs that are identi‐
393       cal except for their defValue and specFlags fields.  One  entry  should
394       have  the  value  TK_CONFIG_MONO_ONLY  in its specFlags and the default
395       value for monochrome displays in its defValue;  the other entry  should
396       have  the value TK_CONFIG_COLOR_ONLY in its specFlags and the appropri‐
397       ate defValue for color displays.
398
399       Third, it is possible to use flags and  specFlags  together  to  selec‐
400       tively  disable  some  entries.  This feature is not needed very often.
401       It is useful in cases where several similar kinds of widgets are imple‐
402       mented in one place.  It allows a single specs table to be created with
403       all the configuration options for all the widget types.  When  process‐
404       ing  a  particular widget type, only entries relevant to that type will
405       be used.  This effect is achieved by setting the high-order bits (those
406       in  positions equal to or greater than TK_CONFIG_USER_BIT) in specFlags
407       values or in flags.  In order for a particular entry  in  specs  to  be
408       used, its high-order bits must match exactly the high-order bits of the
409       flags value passed to Tk_ConfigureWidget.  If a specs  table  is  being
410       used  for  N different widget types, then N of the high-order bits will
411       be used.  Each specs entry will have one of more of those bits  set  in
412       its  specFlags  field to indicate the widget types for which this entry
413       is valid.  When calling Tk_ConfigureWidget, flags will  have  a  single
414       one  of  these  bits  set  to select the entries for the desired widget
415       type.  For a working example of this feature, see the  code  in  tkBut‐
416       ton.c.
417

TK_OFFSET

419       The  Tk_Offset macro is provided as a safe way of generating the offset
420       values for entries in Tk_ConfigSpec structures.   It  takes  two  argu‐
421       ments:   the  name of a type of record, and the name of a field in that
422       record.  It returns the byte offset of the named field  in  records  of
423       the given type.
424

TK_CONFIGUREINFO

426       The  Tk_ConfigureInfo procedure may be used to obtain information about
427       one or all of the options for a given widget.  Given a token for a win‐
428       dow  (tkwin),  a table describing the configuration options for a class
429       of widgets (specs), a pointer to a widget record containing the current
430       information  for  a  widget  (widgRec),  and  a NULL argvName argument,
431       Tk_ConfigureInfo generates a string describing all of the configuration
432       options  for  the window.  The string is placed in interpreter interp's
433       result.  Under normal circumstances it returns  TCL_OK;   if  an  error
434       occurs then it returns TCL_ERROR and the interpreter's result will con‐
435       tain an error message.
436
437       If argvName is NULL, then the value left in the interpreter's result by
438       Tk_ConfigureInfo  consists  of  a  list of one or more entries, each of
439       which describes one configuration option (i.e.  one  entry  in  specs).
440       Each  entry in the list will contain either two or five values.  If the
441       corresponding entry in specs has type TK_CONFIG_SYNONYM, then the  list
442       will  contain  two  values:   the argvName for the entry and the dbName
443       (synonym name).  Otherwise the list will contain  five  values:   argv‐
444       Name,  dbName, dbClass, defValue, and current value.  The current value
445       is computed from the appropriate field of widgRec by calling procedures
446       like Tk_NameOfColor.
447
448       If the argvName argument to Tk_ConfigureInfo is non-NULL, then it indi‐
449       cates a single option,  and  information  is  returned  only  for  that
450       option.   The  string placed in the interpreter's result will be a list
451       containing two or five values as described above;  this will be identi‐
452       cal to the corresponding sublist that would have been returned if argv‐
453       Name had been NULL.
454
455       The flags argument to Tk_ConfigureInfo is used to  restrict  the  specs
456       entries to consider, just as for Tk_ConfigureWidget.
457

TK_CONFIGUREVALUE

459       Tk_ConfigureValue  takes arguments similar to Tk_ConfigureInfo; instead
460       of returning a list of values, it just returns the current value of the
461       option  given  by  argvName  (argvName must not be NULL).  The value is
462       returned in interpreter interp's result and TCL_OK is normally returned
463       as  the  procedure's  result.   If an error occurs in Tk_ConfigureValue
464       (e.g., argvName is not a valid option name), TCL_ERROR is returned  and
465       an  error  message is left in the interpreter's result.  This procedure
466       is typically called to implement cget widget commands.
467

TK_FREEOPTIONS

469       The Tk_FreeOptions procedure may be invoked during  widget  cleanup  to
470       release all of the resources associated with configuration options.  It
471       scans through specs and for each entry corresponding to a resource that
472       must  be  explicitly  freed  (e.g. those with type TK_CONFIG_COLOR), it
473       frees the resource in the widget record.  If the field  in  the  widget
474       record  does not refer to a resource (e.g.  it contains a null pointer)
475       then no resource is freed for that entry.  After  freeing  a  resource,
476       Tk_FreeOptions  sets  the  corresponding  field of the widget record to
477       null.
478

CUSTOM OPTION TYPES

480       Applications can extend the built-in  configuration  types  with  addi‐
481       tional  configuration  types  by  writing procedures to parse and print
482       options of the a type and creating a structure pointing to those proce‐
483       dures:
484              typedef struct Tk_CustomOption {
485                  Tk_OptionParseProc *parseProc;
486                  Tk_OptionPrintProc *printProc;
487                  ClientData clientData;
488              } Tk_CustomOption;
489
490              typedef int Tk_OptionParseProc(
491                      ClientData clientData,
492                      Tcl_Interp *interp,
493                      Tk_Window tkwin,
494                      char *value,
495                      char *widgRec,
496                      int offset);
497
498              typedef const char *Tk_OptionPrintProc(
499                      ClientData clientData,
500                      Tk_Window tkwin,
501                      char *widgRec,
502                      int offset,
503                      Tcl_FreeProc **freeProcPtr);
504       The Tk_CustomOption structure contains three fields, which are pointers
505       to the two procedures and a clientData value to be passed to those pro‐
506       cedures  when  they are invoked.  The clientData value typically points
507       to a structure containing information that is needed by the  procedures
508       when they are parsing and printing options.
509
510       The  parseProc  procedure  is  invoked by Tk_ConfigureWidget to parse a
511       string and store the resulting value in the widget record.  The client‐
512       Data  argument is a copy of the clientData field in the Tk_CustomOption
513       structure.  The interp argument points to a Tcl  interpreter  used  for
514       error  reporting.   Tkwin is a copy of the tkwin argument to Tk_Config‐
515       ureWidget.  The value argument is a string describing the value for the
516       option;  it could have been specified explicitly in the call to Tk_Con‐
517       figureWidget or it could come from the option database  or  a  default.
518       Value will never be a null pointer but it may point to an empty string.
519       RecordPtr is the same as the widgRec  argument  to  Tk_ConfigureWidget;
520       it  points to the start of the widget record to modify.  The last argu‐
521       ment, offset, gives the offset in bytes from the start  of  the  widget
522       record  to  the  location  where the option value is to be placed.  The
523       procedure should translate the string to whatever form  is  appropriate
524       for  the  option  and  store the value in the widget record.  It should
525       normally return TCL_OK, but if  an  error  occurs  in  translating  the
526       string  to  a  value then it should return TCL_ERROR and store an error
527       message in interpreter interp's result.
528
529       The printProc procedure is called  by  Tk_ConfigureInfo  to  produce  a
530       string  value  describing  an  existing option.  Its clientData, tkwin,
531       widgRec, and  offset  arguments  all  have  the  same  meaning  as  for
532       Tk_OptionParseProc  procedures.  The printProc procedure should examine
533       the option whose value is stored at offset in widgRec, produce a string
534       describing  that  option,  and  return a pointer to the string.  If the
535       string is stored in dynamically-allocated memory,  then  the  procedure
536       must set *freeProcPtr to the address of a procedure to call to free the
537       string's memory;  Tk_ConfigureInfo will call this procedure when it  is
538       finished  with  the  string.   If the result string is stored in static
539       memory then printProc need not do anything with the  freeProcPtr  argu‐
540       ment.
541
542       Once  parseProc  and  printProc have been defined and a Tk_CustomOption
543       structure has been created for them, options of this new  type  may  be
544       manipulated  with  Tk_ConfigSpec  entries whose type fields are TK_CON‐
545       FIG_CUSTOM and whose customPtr  fields  point  to  the  Tk_CustomOption
546       structure.
547

EXAMPLES

549       Although  the  explanation of Tk_ConfigureWidget is fairly complicated,
550       its actual use is pretty  straightforward.   The  easiest  way  to  get
551       started  is  to  copy  the  code  from an existing widget.  The library
552       implementation of frames (tkFrame.c) has a simple configuration  table,
553       and  the library implementation of buttons (tkButton.c) has a much more
554       complex table that uses many of the fancy specFlags mechanisms.
555

SEE ALSO

557       Tk_SetOptions(3)
558

KEYWORDS

560       anchor,  bitmap,  boolean,  border,  cap  style,  color,  configuration
561       options,  cursor,  custom,  double, font, integer, join style, justify,
562       millimeters, pixels, relief, synonym, uid
563
564
565
566Tk                                    4.1                Tk_ConfigureWidget(3)
Impressum