1# Copyright (c) 1990-1994 The Regents of the University of California. 2# Copyright (c) 1994-1996 Sun Microsystems, Inc. 3# See the file "license.terms" for information on usage and redistribution 4# of this file, and for a DISCLAIMER OF ALL WARRANTIES. 5# 6# 7 8=head1 NAME 9 10Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions - process configuration options for widgets 11 12=for category C Programming 13 14=head1 SYNOPSIS 15 16B<#include E<lt>tk.hE<gt>> 17 18int 19B<Tk_ConfigureWidget(>I<interp, tkwin, specs, argc, argv, widgRec, flags>B<)> 20 21int 22B<Tk_Offset(>I<type, field>B<)> 23 24int 25B<Tk_ConfigureInfo(>I<interp, tkwin, specs, widgRec, argvName, flags>B<)> 26 27int 28 29B<Tk_FreeOptions(>I<specs, widgRec, display, flags>B<)> 30 31=head1 ARGUMENTS 32 33=over 4 34 35=item Tcl_Interp *interp (in) 36 37Interpreter to use for returning error messages. 38 39=item Tk_Window tkwin (in) 40 41Window used to represent widget (needed to set up X resources). 42 43=item Tk_ConfigSpec *specs (in) 44 45Pointer to table specifying legal configuration options for this 46widget. 47 48=item int argc (in) 49 50Number of arguments in I<argv>. 51 52=item char **argv (in) 53 54Command-line options for configuring widget. 55 56=item char *widgRec (in/out) 57 58Points to widget record structure. Fields in this structure get 59modified by B<Tk_ConfigureWidget> to hold configuration information. 60 61=item int flags (in) 62 63If non-zero, then it specifies an OR-ed combination of flags that 64control the processing of configuration information. 65TK_CONFIG_ARGV_ONLY causes the option database and defaults to be 66ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to 67selectively disable entries in I<specs>. 68 69=item "type name" type (in) 70 71The name of the type of a widget record. 72 73=item "field name" field (in) 74 75The name of a field in records of type I<type>. 76 77=item char *argvName (in) 78 79The name used on Tcl command lines to refer to a particular option 80(e.g. when creating a widget or invoking the B<configure> widget 81command). If non-NULL, then information is returned only for this 82option. If NULL, then information is returned for all available 83options. 84 85=item Display *display (in) 86 87Display containing widget whose record is being freed; needed in 88order to free up resources. 89 90=back 91 92=head1 DESCRIPTION 93 94B<Tk_ConfigureWidget> is called to configure various aspects of a 95widget, such as colors, fonts, border width, etc. 96It is intended as a convenience procedure to reduce the amount 97of code that must be written in individual widget managers to 98handle configuration information. 99It is typically 100invoked when widgets are created, and again when the B<configure> 101command is invoked for a widget. 102Although intended primarily for widgets, B<Tk_ConfigureWidget> 103can be used in other situations where I<argc-argv> information 104is to be used to fill in a record structure, such as configuring 105graphical elements for a canvas widget or entries of a menu. 106 107B<Tk_ConfigureWidget> processes 108a table specifying the configuration options that are supported 109(I<specs>) and a collection of command-line arguments (I<argc> and 110I<argv>) to fill in fields of a record (I<widgRec>). 111It uses the option database and defaults specified in I<specs> 112to fill in fields of I<widgRec> that are not specified in I<argv>. 113B<Tk_ConfigureWidget> normally returns the value TCL_OK; in this 114case it does not modify I<interp>. 115If an error 116occurs then TCL_ERROR is returned and B<Tk_ConfigureWidget> will 117leave an error message in I<interp-E<gt>result> in the standard Tcl 118fashion. 119In the event of an error return, some of the fields of I<widgRec> 120could already have been set, if configuration information for them 121was successfully processed before the error occurred. 122The other fields will be set to reasonable initial values so that 123B<Tk_FreeOptions> can be called for cleanup. 124 125The I<specs> array specifies the kinds of configuration options 126expected by the widget. Each of its entries specifies one configuration 127option and has the following structure: 128 129 typedef struct { 130 int type; 131 char *argvName; 132 char *dbName; 133 char *dbClass; 134 char *defValue; 135 int offset; 136 int specFlags; 137 Tk_CustomOption *customPtr; 138 } Tk_ConfigSpec; 139 140The I<type> field indicates what type of configuration option this is 141(e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for 142an integer value). The I<type> field indicates how to use the 143value of the option (more on this below). 144The I<argvName> field is a string such as ``-font'' or ``-bg'', 145which is compared with the values in I<argv> (if I<argvName> is 146NULL it means this is a grouped entry; see L</GROUPED ENTRIES> below). The 147I<dbName> and I<dbClass> fields are used to look up a value 148for this option in the option database. The I<defValue> field 149specifies a default value for this configuration option if no 150value is specified in either I<argv> or the option database. 151I<Offset> indicates where in I<widgRec> to store information 152about this option, and I<specFlags> contains additional information 153to control the processing of this configuration option (see FLAGS 154below). 155The last field, I<customPtr>, is only used if I<type> is 156TK_CONFIG_CUSTOM; see L</CUSTOM OPTION TYPES> below. 157 158B<Tk_ConfigureWidget> first processes I<argv> to see which 159(if any) configuration options are specified there. I<Argv> 160must contain an even number of fields; the first of each pair 161of fields must match the I<argvName> of some entry in I<specs> 162(unique abbreviations are acceptable), 163and the second field of the pair contains the value for that 164configuration option. If there are entries in I<spec> for which 165there were no matching entries in I<argv>, 166B<Tk_ConfigureWidget> uses the I<dbName> and I<dbClass> 167fields of the I<specs> entry to probe the option database; if 168a value is found, then it is used as the value for the option. 169Finally, if no entry is found in the option database, the 170I<defValue> field of the I<specs> entry is used as the 171value for the configuration option. If the I<defValue> is 172NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in 173I<flags>, then there is no default value and this I<specs> entry 174will be ignored if no value is specified in I<argv> or the 175option database. 176 177Once a string value has been determined for a configuration option, 178B<Tk_ConfigureWidget> translates the string value into a more useful 179form, such as a color if I<type> is TK_CONFIG_COLOR or an integer 180if I<type> is TK_CONFIG_INT. This value is then stored in the 181record pointed to by I<widgRec>. This record is assumed to 182contain information relevant to the manager of the widget; its exact 183type is unknown to B<Tk_ConfigureWidget>. The I<offset> field 184of each I<specs> entry indicates where in I<widgRec> to store 185the information about this configuration option. You should use the 186B<Tk_Offset> macro to generate I<offset> values (see below for 187a description of B<Tk_Offset>). The location indicated by 188I<widgRec> and I<offset> will be referred to as the ``target'' 189in the descriptions below. 190 191The I<type> field of each entry in I<specs> determines what 192to do with the string value of that configuration option. The 193legal values for I<type>, and the corresponding actions, are: 194 195=over 4 196 197=item B<TK_CONFIG_ACTIVE_CURSOR> 198 199The value 200must be an ASCII string identifying a cursor in a form 201suitable for passing to B<Tk_GetCursor>. 202The value is converted to a B<Tk_Cursor> by calling 203B<Tk_GetCursor> and the result is stored in the target. 204In addition, the resulting cursor is made the active cursor 205for I<tkwin> by calling B<XDefineCursor>. 206If TK_CONFIG_NULL_OK is specified in I<specFlags> then the value 207may be an empty string, in which case the target and I<tkwin>'s 208active cursor will be set to B<None>. 209If the previous value of the target 210wasn't B<None>, then it is freed by passing it to B<Tk_FreeCursor>. 211 212=item B<TK_CONFIG_ANCHOR> 213 214The value must be an ASCII string identifying an anchor point in one of the ways 215accepted by B<Tk_GetAnchor>. 216The string is converted to a B<Tk_Anchor> by calling 217B<Tk_GetAnchor> and the result is stored in the target. 218 219=item B<TK_CONFIG_BITMAP> 220 221The value must be an ASCII string identifying a bitmap in a form 222suitable for passing to B<Tk_GetBitmap>. The value is converted 223to a B<Pixmap> by calling B<Tk_GetBitmap> and the result 224is stored in the target. 225If TK_CONFIG_NULL_OK is specified in I<specFlags> then the value 226may be an empty string, in which case the target is set to B<None>. 227If the previous value of the target 228wasn't B<None>, then it is freed by passing it to B<Tk_FreeBitmap>. 229 230=item B<TK_CONFIG_BOOLEAN> 231 232The value must be an ASCII string specifying a boolean value. Any 233of the values ``true'', ``yes'', ``on'', or ``1'', 234or an abbreviation of one of these values, means true; 235any of the values ``false'', ``no'', ``off'', or ``0'', or an abbreviation of 236one of these values, means false. 237The target is expected to be an integer; for true values it will 238be set to 1 and for false values it will be set to 0. 239 240=item B<TK_CONFIG_BORDER> 241 242The value must be an ASCII string identifying a border color in a form 243suitable for passing to B<Tk_Get3DBorder>. The value is converted 244to a (B<Tk_3DBorder *>) by calling B<Tk_Get3DBorder> and the result 245is stored in the target. 246If TK_CONFIG_NULL_OK is specified in I<specFlags> then the value 247may be an empty string, in which case the target will be set to NULL. 248If the previous value of the target 249wasn't NULL, then it is freed by passing it to B<Tk_Free3DBorder>. 250 251=item B<TK_CONFIG_CAP_STYLE> 252 253The value must be 254an ASCII string identifying a cap style in one of the ways 255accepted by B<Tk_GetCapStyle>. 256The string is converted to an integer value corresponding 257to the cap style by calling 258B<Tk_GetCapStyle> and the result is stored in the target. 259 260=item B<TK_CONFIG_COLOR> 261 262The value must be an ASCII string identifying a color in a form 263suitable for passing to B<Tk_GetColor>. The value is converted 264to an (B<XColor *>) by calling B<Tk_GetColor> and the result 265is stored in the target. 266If TK_CONFIG_NULL_OK is specified in I<specFlags> then the value 267may be an empty string, in which case the target will be set to B<None>. 268If the previous value of the target 269wasn't NULL, then it is freed by passing it to B<Tk_FreeColor>. 270 271=item B<TK_CONFIG_CURSOR> 272 273This option is identical to B<TK_CONFIG_ACTIVE_CURSOR> except 274that the new cursor is not made the active one for I<tkwin>. 275 276=item B<TK_CONFIG_CUSTOM> 277 278This option allows applications to define new option types. 279The I<customPtr> field of the entry points to a structure 280defining the new option type. 281See the section L</CUSTOM OPTION TYPES> below for details. 282 283=item B<TK_CONFIG_DOUBLE> 284 285The value must be an ASCII floating-point number in 286the format accepted by B<strtol>. The string is converted 287to a B<double> value, and the value is stored in the 288target. 289 290=item B<TK_CONFIG_END> 291 292Marks the end of the table. The last entry in I<specs> 293must have this type; all of its other fields are ignored and it 294will never match any arguments. 295 296=item B<TK_CONFIG_FONT> 297 298The value must be an ASCII string identifying a font in a form 299suitable for passing to B<Tk_GetFontStruct>. The value is converted 300to an (B<XFontStruct *>) by calling B<Tk_GetFontStruct> and the result 301is stored in the target. 302If TK_CONFIG_NULL_OK is specified in I<specFlags> then the value 303may be an empty string, in which case the target will be set to NULL. 304If the previous value of the target 305wasn't NULL, then it is freed by passing it to B<Tk_FreeFontStruct>. 306 307=item B<TK_CONFIG_INT> 308 309The value must be an ASCII integer string 310in the format accepted by B<strtol> (e.g. ``0'' 311and ``0x'' prefixes may be used to specify octal or hexadecimal 312numbers, respectively). The string is converted to an integer 313value and the integer is stored in the target. 314 315=item B<TK_CONFIG_JOIN_STYLE> 316 317The value must be 318an ASCII string identifying a join style in one of the ways 319accepted by B<Tk_GetJoinStyle>. 320The string is converted to an integer value corresponding 321to the join style by calling 322B<Tk_GetJoinStyle> and the result is stored in the target. 323 324=item B<TK_CONFIG_JUSTIFY> 325 326The value must be 327an ASCII string identifying a justification method in one of the 328ways accepted by B<Tk_GetJustify>. 329The string is converted to a B<Tk_Justify> by calling 330B<Tk_GetJustify> and the result is stored in the target. 331 332=item B<TK_CONFIG_MM> 333 334The value must specify a screen distance in one of the forms acceptable 335to B<Tk_GetScreenMM>. 336The string is converted to double-precision floating-point distance 337in millimeters and the value is stored in the target. 338 339=item B<TK_CONFIG_PIXELS> 340 341The value must specify screen units in one of the forms acceptable 342to B<Tk_GetPixels>. 343The string is converted to an integer distance in pixels and the 344value is stored in the target. 345 346=item B<TK_CONFIG_RELIEF> 347 348The value must be an ASCII string identifying a relief in a form 349suitable for passing to B<Tk_GetRelief>. The value is converted 350to an integer relief value by calling B<Tk_GetRelief> and the result 351is stored in the target. 352 353=item B<TK_CONFIG_STRING> 354 355A copy 356of the value is made by allocating memory space with 357B<malloc> and copying the value into the dynamically-allocated 358space. A pointer to the new string is stored in the target. 359If TK_CONFIG_NULL_OK is specified in I<specFlags> then the value 360may be an empty string, in which case the target will be set to NULL. 361If the previous value of the target wasn't NULL, then it is 362freed by passing it to B<free>. 363 364=item B<TK_CONFIG_SYNONYM> 365 366This I<type> value identifies special entries in I<specs> that 367are synonyms for other entries. If an I<argv> value matches the 368I<argvName> of a TK_CONFIG_SYNONYM entry, the entry isn't used 369directly. Instead, B<Tk_ConfigureWidget> searches I<specs> 370for another entry whose I<argvName> is the same as the I<dbName> 371field in the TK_CONFIG_SYNONYM entry; this new entry is used just 372as if its I<argvName> had matched the I<argv> value. The 373synonym mechanism allows multiple I<argv> values to be used for 374a single configuration option, such as ``-background'' and ``-bg''. 375 376=item B<TK_CONFIG_UID> 377 378The value is translated to a B<Tk_Uid> 379(by passing it to B<Tk_GetUid>). The resulting value 380is stored in the target. 381If TK_CONFIG_NULL_OK is specified in I<specFlags> and the value 382is an empty string then the target will be set to NULL. 383 384=item B<TK_CONFIG_WINDOW> 385 386The value must be a window path name. It is translated to a 387B<Tk_Window> token and the token is stored in the target. 388 389=back 390 391=head1 GROUPED ENTRIES 392 393In some cases it is useful to generate multiple resources from 394a single configuration value. For example, a color name might 395be used both to generate the background color for a widget (using 396TK_CONFIG_COLOR) and to generate a 3-D border to draw around the 397widget (using TK_CONFIG_BORDER). In cases like this it is possible 398to specify that several consecutive entries in I<specs> are to 399be treated as a group. The first entry is used to determine a value 400(using its I<argvName>, I<dbName>, 401I<dbClass>, and I<defValue> fields). The value will be processed 402several times (one for each entry in the group), generating multiple 403different resources and modifying multiple targets within I<widgRec>. 404Each of the entries after the first must have a NULL value in its 405I<argvName> field; this indicates that the entry is to be grouped 406with the entry that precedes it. Only the I<type> and I<offset> 407fields are used from these follow-on entries. 408 409=head1 FLAGS 410 411The I<flags> argument passed to B<Tk_ConfigureWidget> is used 412in conjunction with the I<specFlags> fields in the entries of I<specs> 413to provide additional control over the processing of configuration 414options. These values are used in three different ways as 415described below. 416 417First, if the I<flags> argument to B<Tk_ConfigureWidget> has 418the TK_CONFIG_ARGV_ONLY bit set (i.e., I<flags> | TK_CONFIG_ARGV_ONLY != 0), 419then the option database and 420I<defValue> fields are not used. In this case, if an entry in 421I<specs> doesn't match a field in I<argv> then nothing happens: 422the corresponding target isn't modified. This feature is useful 423when the goal is to modify certain configuration options while 424leaving others in their current state, such as when a B<configure> 425method is being processed. 426 427Second, the I<specFlags> field of an entry in I<specs> may be used 428to control the processing of that entry. Each I<specFlags> 429field may consists of an OR-ed combination of the following values: 430 431=over 4 432 433=item B<TK_CONFIG_COLOR_ONLY> 434 435If this bit is set then the entry will only be considered if the 436display for I<tkwin> has more than one bit plane. If the display 437is monochromatic then this I<specs> entry will be ignored. 438 439=item B<TK_CONFIG_MONO_ONLY> 440 441If this bit is set then the entry will only be considered if the 442display for I<tkwin> has exactly one bit plane. If the display 443is not monochromatic then this I<specs> entry will be ignored. 444 445=item B<TK_CONFIG_NULL_OK> 446 447This bit is only relevant for some types of entries (see the 448descriptions of the various entry types above). 449If this bit is set, it indicates that an empty string value 450for the field is acceptable and if it occurs then the 451target should be set to NULL or B<None>, depending 452on the type of the target. 453This flag is typically used to allow a 454feature to be turned off entirely, e.g. set a cursor value to 455B<None> so that a window simply inherits its parent's cursor. 456If this bit isn't set then empty strings are processed as strings, 457which generally results in an error. 458 459=item B<TK_CONFIG_DONT_SET_DEFAULT> 460 461If this bit is one, it means that the I<defValue> field of the 462entry should only be used for returning the default value in 463B<Tk_ConfigureInfo>. 464In calls to B<Tk_ConfigureWidget> no default will be supplied 465for entries with this flag set; it is assumed that the 466caller has already supplied a default value in the target location. 467This flag provides a performance optimization where it is expensive 468to process the default string: the client can compute the default 469once, save the value, and provide it before calling 470B<Tk_ConfigureWidget>. 471 472=item B<TK_CONFIG_OPTION_SPECIFIED> 473 474This bit is set and cleared by B<Tk_ConfigureWidget>. Whenever 475B<Tk_ConfigureWidget> returns, this bit will be set in all the 476entries where a value was specified in I<argv>. 477It will be zero in all other entries. 478This bit provides a way for clients to determine which values 479actually changed in a call to B<Tk_ConfigureWidget>. 480 481The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically 482used to specify different default values for 483monochrome and color displays. This is done by creating two 484entries in I<specs> that are identical except for their 485I<defValue> and I<specFlags> fields. One entry should have 486the value TK_CONFIG_MONO_ONLY in its I<specFlags> and the 487default value for monochrome displays in its I<defValue>; the 488other entry entry should have the value TK_CONFIG_COLOR_ONLY in 489its I<specFlags> and the appropriate I<defValue> for 490color displays. 491 492Third, it is possible to use I<flags> and I<specFlags> 493together to selectively disable some entries. This feature is 494not needed very often. It is useful in cases where several 495similar kinds of widgets are implemented in one place. It allows 496a single I<specs> table to be created with all the configuration 497options for all the widget types. When processing a particular 498widget type, only entries relevant to that type will be used. This 499effect is achieved by setting the high-order bits (those in positions 500equal to or greater than TK_CONFIG_USER_BIT) in I<specFlags> 501values or in I<flags>. In order for a particular entry in 502I<specs> to be used, its high-order bits must match exactly 503the high-order bits of the I<flags> value passed to 504B<Tk_ConfigureWidget>. If a I<specs> table is being used 505for N different widget types, then N of the high-order bits will 506be used. Each I<specs> entry will have one of more of those 507bits set in its I<specFlags> field to indicate the widget types 508for which this entry is valid. When calling B<Tk_ConfigureWidget>, 509I<flags> will have a single one of these bits set to select the 510entries for the desired widget type. For a working example of 511this feature, see the code in tkButton.c. 512 513=back 514 515=head1 TK_OFFSET 516 517The B<Tk_Offset> macro is provided as a safe way of generating 518the I<offset> values for entries in Tk_ConfigSpec structures. 519It takes two arguments: the name of a type of record, and the 520name of a field in that record. It returns the byte offset of 521the named field in records of the given type. 522 523=head1 TK_CONFIGUREINFO 524 525The B<Tk_ConfigureInfo> procedure may be used to obtain 526information about one or all of the options for a given widget. 527Given a token for a window (I<tkwin>), a table describing the 528configuration options for a class of widgets (I<specs>), a 529pointer to a widget record containing the current information for 530a widget (I<widgRec>), and a NULL I<argvName> argument, 531B<Tk_ConfigureInfo> generates a string describing all of the 532configuration options for the window. The string is placed 533in I<interp-E<gt>result>. Under normal circumstances 534it returns TCL_OK; if an error occurs then it returns TCL_ERROR 535and I<interp-E<gt>result> contains an error message. 536 537If I<argvName> is NULL, then the value left in 538I<interp-E<gt>result> by B<Tk_ConfigureInfo> 539consists of a list of one or more entries, each of which describes 540one configuration option (i.e. one entry in I<specs>). Each 541entry in the list will contain either two or five values. If the 542corresponding entry in I<specs> has type TK_CONFIG_SYNONYM, then 543the list will contain two values: the I<argvName> for the entry 544and the I<dbName> (synonym name). Otherwise the list will contain 545five values: I<argvName>, I<dbName>, I<dbClass>, I<defValue>, 546and current value. The current value is computed from the appropriate 547field of I<widgRec> by calling procedures like B<Tk_NameOfColor>. 548 549If the I<argvName> argument to B<Tk_ConfigureInfo> is non-NULL, 550then it indicates a single option, and information is returned only 551for that option. The string placed in I<interp-E<gt>result> will be 552a list containing two or five values as described above; this will 553be identical to the corresponding sublist that would have been returned 554if I<argvName> had been NULL. 555 556The I<flags> argument to B<Tk_ConfigureInfo> is used to restrict 557the I<specs> entries to consider, just as for B<Tk_ConfigureWidget>. 558 559=head1 TK_CONFIGUREVALUE 560 561B<Tk_ConfigureValue> takes arguments similar to B<Tk_ConfigureInfo>; 562instead of returning a list of values, it just returns the current value 563of the option given by I<argvName> (I<argvName> must not be NULL). 564The value is returned in I<interp-E<gt>result> and TCL_OK is 565normally returned as the procedure's result. 566If an error occurs in B<Tk_ConfigureValue> (e.g., I<argvName> is 567not a valid option name), TCL_ERROR is returned and an error message 568is left in I<interp-E<gt>result>. 569This procedure is typically called to implement B<cget> widget 570commands. 571 572=head1 TK_FREEOPTIONS 573 574The B<Tk_FreeOptions> procedure may be invoked during widget cleanup 575to release all of the resources associated with configuration options. 576It scans through I<specs> and for each entry corresponding to a 577resource that must be explicitly freed (e.g. those with 578type TK_CONFIG_COLOR), it frees the resource in the widget record. 579If the field in the widget record doesn't refer to a resource (e.g. 580it contains a null pointer) then no resource is freed for that 581entry. 582After freeing a resource, B<Tk_FreeOptions> sets the 583corresponding field of the widget record to null. 584 585=head1 CUSTOM OPTION TYPES 586 587Applications can extend the built-in configuration types with additional 588configuration types by writing procedures to parse and print options 589of the a type and creating a structure pointing to those procedures: 590 591 typedef struct Tk_CustomOption { 592 Tk_OptionParseProc *parseProc; 593 Tk_OptionPrintProc *printProc; 594 ClientData clientData; 595 } Tk_CustomOption; 596 597 typedef int Tk_OptionParseProc( 598 ClientData clientData, 599 Tcl_Interp *interp, 600 Tk_Window tkwin, 601 char *value, 602 char *widgRec, 603 int offset); 604 605 typedef char *Tk_OptionPrintProc( 606 ClientData clientData, 607 Tk_Window tkwin, 608 char *widgRec, 609 int offset, 610 Tcl_FreeProc **freeProcPtr); 611 612The Tk_CustomOption structure contains three fields, which are pointers 613to the two procedures and a I<clientData> value to be passed to those 614procedures when they are invoked. The I<clientData> value typically 615points to a structure containing information that is needed by the 616procedures when they are parsing and printing options. 617 618The I<parseProc> procedure is invoked by 619B<Tk_ConfigureWidget> to parse a string and store the resulting 620value in the widget record. 621The I<clientData> argument is a copy of the I<clientData> 622field in the Tk_CustomOption structure. 623The I<interp> argument points to a Tcl interpreter used for 624error reporting. I<Tkwin> is a copy of the I<tkwin> argument 625to B<Tk_ConfigureWidget>. The I<value> argument is a string 626describing the value for the option; it could have been specified 627explicitly in the call to B<Tk_ConfigureWidget> or it could 628come from the option database or a default. 629I<Value> will never be a null pointer but it may point to 630an empty string. 631I<RecordPtr> is the same as the I<widgRec> argument to 632B<Tk_ConfigureWidget>; it points to the start of the widget 633record to modify. 634The last argument, I<offset>, gives the offset in bytes from the start 635of the widget record to the location where the option value is to 636be placed. The procedure should translate the string to whatever 637form is appropriate for the option and store the value in the widget 638record. It should normally return TCL_OK, but if an error occurs 639in translating the string to a value then it should return TCL_ERROR 640and store an error message in I<interp-E<gt>result>. 641 642The I<printProc> procedure is called 643by B<Tk_ConfigureInfo> to produce a string value describing an 644existing option. 645Its I<clientData>, I<tkwin>, I<widgRec>, and I<offset> 646arguments all have the same meaning as for Tk_OptionParseProc 647procedures. 648The I<printProc> procedure should examine the option whose value 649is stored at I<offset> in I<widgRec>, produce a string describing 650that option, and return a pointer to the string. 651If the string is stored in dynamically-allocated memory, then 652the procedure must set I<*freeProcPtr> to the address of 653a procedure to call to free the string's memory; B<Tk_ConfigureInfo> 654will call this procedure when it is finished with the string. 655If the result string is stored in static memory then I<printProc> 656need not do anything with the I<freeProcPtr> argument. 657 658Once I<parseProc> and I<printProc> have been defined and a 659Tk_CustomOption structure has been created for them, options of this 660new type may be manipulated with Tk_ConfigSpec entries whose I<type> 661fields are TK_CONFIG_CUSTOM and whose I<customPtr> fields point 662to the Tk_CustomOption structure. 663 664=head1 EXAMPLES 665 666Although the explanation of B<Tk_ConfigureWidget> is fairly 667complicated, its actual use is pretty straightforward. 668The easiest way to get started is to copy the code 669from an existing widget. 670The library implementation of frames 671(tkFrame.c) has a simple configuration table, and the library 672implementation of buttons (tkButton.c) has a much more complex 673table that uses many of the fancy I<specFlags> mechanisms. 674 675=head1 KEYWORDS 676 677anchor, bitmap, boolean, border, cap style, color, configuration options, 678cursor, custom, double, font, integer, join style, justify, millimeters, 679pixels, relief, synonym, uid 680