Initial revision

1 files changed, 618 insertions, 0 deletions

diff --git a/doc/ConfigWidg.3 b/doc/ConfigWidg.3
new file mode 100644
index 0000000..3178580
--- /dev/null
+++ b/doc/ConfigWidg.3
@@ -0,0 +1,618 @@
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" SCCS: @(#) ConfigWidg.3 1.30 96/08/27 13:21:18
+'\" 
+.so man.macros
+.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures"
+.BS
+.SH NAME
+Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR
+.sp
+int
+\fBTk_Offset(\fItype, field\fB)\fR
+.sp
+int
+\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
+.sp
+int
+.sp
+\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR
+.SH ARGUMENTS
+.AS Tk_ConfigSpec *widgRec
+.AP Tcl_Interp *interp in
+Interpreter to use for returning error messages.
+.AP Tk_Window tkwin in
+Window used to represent widget (needed to set up X resources).
+.AP Tk_ConfigSpec *specs in
+Pointer to table specifying legal configuration options for this
+widget.
+.AP int argc in
+Number of arguments in \fIargv\fR.
+.AP char **argv in
+Command-line options for configuring widget.
+.AP char *widgRec in/out
+Points to widget record structure.  Fields in this structure get
+modified by \fBTk_ConfigureWidget\fR to hold configuration information.
+.AP int flags in
+If non-zero, then it specifies an OR-ed combination of flags that
+control the processing of configuration information.
+TK_CONFIG_ARGV_ONLY causes the option database and defaults to be
+ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to
+selectively disable entries in \fIspecs\fR.
+.AP "type name" type in
+The name of the type of a widget record.
+.AP "field name" field in
+The name of a field in records of type \fItype\fR.
+.AP char *argvName in
+The name used on Tcl command lines to refer to a particular option
+(e.g. when creating a widget or invoking the \fBconfigure\fR widget
+command).  If non-NULL, then information is returned only for this
+option.  If NULL, then information is returned for all available
+options.
+.AP Display *display in
+Display containing widget whose record is being freed;  needed in
+order to free up resources.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_ConfigureWidget\fR is called to configure various aspects of a
+widget, such as colors, fonts, border width, etc.
+It is intended as a convenience procedure to reduce the amount
+of code that must be written in individual widget managers to
+handle configuration information.
+It is typically
+invoked when widgets are created, and again when the \fBconfigure\fR
+command is invoked for a widget.
+Although intended primarily for widgets, \fBTk_ConfigureWidget\fR
+can be used in other situations where \fIargc-argv\fR information
+is to be used to fill in a record structure, such as configuring
+graphical elements for a canvas widget or entries of a menu.
+.PP
+\fBTk_ConfigureWidget\fR processes
+a table specifying the configuration options that are supported
+(\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and
+\fIargv\fR) to fill in fields of a record (\fIwidgRec\fR).
+It uses the option database and defaults specified in \fIspecs\fR
+to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR.
+\fBTk_ConfigureWidget\fR normally returns the value TCL_OK; in this
+case it does not modify \fIinterp\fR.
+If an error
+occurs then TCL_ERROR is returned and \fBTk_ConfigureWidget\fR will
+leave an error message in \fIinterp->result\fR in the standard Tcl
+fashion.
+In the event of an error return, some of the fields of \fIwidgRec\fR
+could already have been set, if configuration information for them
+was successfully processed before the error occurred.
+The other fields will be set to reasonable initial values so that
+\fBTk_FreeOptions\fR can be called for cleanup.
+.PP
+The \fIspecs\fR array specifies the kinds of configuration options
+expected by the widget.  Each of its entries specifies one configuration
+option and has the following structure:
+.CS
+typedef struct {
+	int \fItype\fR;
+	char *\fIargvName\fR;
+	char *\fIdbName\fR;
+	char *\fIdbClass\fR;
+	char *\fIdefValue\fR;
+	int \fIoffset\fR;
+	int \fIspecFlags\fR;
+	Tk_CustomOption *\fIcustomPtr\fR;
+} Tk_ConfigSpec;
+.CE
+The \fItype\fR field indicates what type of configuration option this is
+(e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for
+an integer value).  The \fItype\fR field indicates how to use the
+value of the option (more on this below).
+The \fIargvName\fR field is a string such as ``\-font'' or ``\-bg'',
+which is compared with the values in \fIargv\fR (if \fIargvName\fR is
+NULL it means this is a grouped entry;  see GROUPED ENTRIES below).  The
+\fIdbName\fR and \fIdbClass\fR fields are used to look up a value
+for this option in the option database.  The \fIdefValue\fR field
+specifies a default value for this configuration option if no
+value is specified in either \fIargv\fR or the option database.
+\fIOffset\fR indicates where in \fIwidgRec\fR to store information
+about this option, and \fIspecFlags\fR contains additional information
+to control the processing of this configuration option (see FLAGS
+below).
+The last field, \fIcustomPtr\fR, is only used if \fItype\fR is
+TK_CONFIG_CUSTOM;  see CUSTOM OPTION TYPES below.
+.PP
+\fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which
+(if any) configuration options are specified there.  \fIArgv\fR
+must contain an even number of fields;  the first of each pair
+of fields must match the \fIargvName\fR of some entry in \fIspecs\fR
+(unique abbreviations are acceptable),
+and the second field of the pair contains the value for that
+configuration option.  If there are entries in \fIspec\fR for which
+there were no matching entries in \fIargv\fR,
+\fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR
+fields of the \fIspecs\fR entry to probe the option database;  if
+a value is found, then it is used as the value for the option.
+Finally, if no entry is found in the option database, the
+\fIdefValue\fR field of the \fIspecs\fR entry is used as the
+value for the configuration option.  If the \fIdefValue\fR is
+NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in
+\fIflags\fR, then there is no default value and this \fIspecs\fR entry
+will be ignored if no value is specified in \fIargv\fR or the
+option database.
+.PP
+Once a string value has been determined for a configuration option,
+\fBTk_ConfigureWidget\fR translates the string value into a more useful
+form, such as a color if \fItype\fR is TK_CONFIG_COLOR or an integer
+if \fItype\fR is TK_CONFIG_INT.  This value is then stored in the
+record pointed to by \fIwidgRec\fR.  This record is assumed to
+contain information relevant to the manager of the widget;  its exact
+type is unknown to \fBTk_ConfigureWidget\fR.  The \fIoffset\fR field
+of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store
+the information about this configuration option.  You should use the
+\fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for
+a description of \fBTk_Offset\fR).  The location indicated by
+\fIwidgRec\fR and \fIoffset\fR will be referred to as the ``target''
+in the descriptions below.
+.PP
+The \fItype\fR field of each entry in \fIspecs\fR determines what
+to do with the string value of that configuration option.  The
+legal values for \fItype\fR, and the corresponding actions, are:
+.TP
+\fBTK_CONFIG_ACTIVE_CURSOR\fR
+The value
+must be an ASCII string identifying a cursor in a form
+suitable for passing to \fBTk_GetCursor\fR. 
+The value is converted to a \fBTk_Cursor\fR by calling
+\fBTk_GetCursor\fR and the result is stored in the target.
+In addition, the resulting cursor is made the active cursor
+for \fItkwin\fR by calling \fBXDefineCursor\fR.
+If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target and \fItkwin\fR's
+active cursor will be set to \fBNone\fR.
+If the previous value of the target
+wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
+.TP
+\fBTK_CONFIG_ANCHOR\fR
+The value must be an ASCII string identifying an anchor point in one of the ways
+accepted by \fBTk_GetAnchor\fR.
+The string is converted to a \fBTk_Anchor\fR by calling
+\fBTk_GetAnchor\fR and the result is stored in the target.
+.TP
+\fBTK_CONFIG_BITMAP\fR
+The value must be an ASCII string identifying a bitmap in a form
+suitable for passing to \fBTk_GetBitmap\fR.  The value is converted
+to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result
+is stored in the target.
+If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target is set to \fBNone\fR.
+If the previous value of the target
+wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
+.TP
+\fBTK_CONFIG_BOOLEAN\fR
+The value must be an ASCII string specifying a boolean value.  Any
+of the values ``true'', ``yes'', ``on'', or ``1'',
+or an abbreviation of one of these values, means true;
+any of the values ``false'', ``no'', ``off'', or ``0'', or an abbreviation of
+one of these values, means false.
+The target is expected to be an integer;  for true values it will
+be set to 1 and for false values it will be set to 0.
+.TP
+\fBTK_CONFIG_BORDER\fR
+The value must be an ASCII string identifying a border color in a form
+suitable for passing to \fBTk_Get3DBorder\fR.  The value is converted
+to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result
+is stored in the target.
+If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target will be set to NULL.
+If the previous value of the target
+wasn't NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
+.TP
+\fBTK_CONFIG_CAP_STYLE\fR
+The value must be
+an ASCII string identifying a cap style in one of the ways
+accepted by \fBTk_GetCapStyle\fR.
+The string is converted to an integer value corresponding
+to the cap style by calling
+\fBTk_GetCapStyle\fR and the result is stored in the target.
+.TP
+\fBTK_CONFIG_COLOR\fR
+The value must be an ASCII string identifying a color in a form
+suitable for passing to \fBTk_GetColor\fR.  The value is converted
+to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result
+is stored in the target.
+If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target will be set to \fBNone\fR.
+If the previous value of the target
+wasn't NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
+.TP
+\fBTK_CONFIG_CURSOR\fR
+This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except
+that the new cursor is not made the active one for \fItkwin\fR.
+.TP
+\fBTK_CONFIG_CUSTOM\fR
+This option allows applications to define new option types.
+The \fIcustomPtr\fR field of the entry points to a structure
+defining the new option type.
+See the section CUSTOM OPTION TYPES below for details.
+.TP
+\fBTK_CONFIG_DOUBLE\fR
+The value must be an ASCII floating-point number in
+the format accepted by \fBstrtol\fR.  The string is converted
+to a \fBdouble\fR value, and the value is stored in the
+target.
+.TP
+\fBTK_CONFIG_END\fR
+Marks the end of the table.  The last entry in \fIspecs\fR
+must have this type;  all of its other fields are ignored and it
+will never match any arguments.
+.TP
+\fBTK_CONFIG_FONT\fR
+The value must be an ASCII string identifying a font in a form
+suitable for passing to \fBTk_GetFontStruct\fR.  The value is converted
+to an (\fBXFontStruct *\fR) by calling \fBTk_GetFontStruct\fR and the result
+is stored in the target.
+If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target will be set to NULL.
+If the previous value of the target
+wasn't NULL, then it is freed by passing it to \fBTk_FreeFontStruct\fR.
+.TP
+\fBTK_CONFIG_INT\fR
+The value must be an ASCII integer string
+in the format accepted by \fBstrtol\fR (e.g. ``0''
+and ``0x'' prefixes may be used to specify octal or hexadecimal
+numbers, respectively).  The string is converted to an integer
+value and the integer is stored in the target.
+.TP
+\fBTK_CONFIG_JOIN_STYLE\fR
+The value must be
+an ASCII string identifying a join style in one of the ways
+accepted by \fBTk_GetJoinStyle\fR.
+The string is converted to an integer value corresponding
+to the join style by calling
+\fBTk_GetJoinStyle\fR and the result is stored in the target.
+.TP
+\fBTK_CONFIG_JUSTIFY\fR
+The value must be
+an ASCII string identifying a justification method in one of the
+ways accepted by \fBTk_GetJustify\fR.
+The string is converted to a \fBTk_Justify\fR by calling
+\fBTk_GetJustify\fR and the result is stored in the target.
+.TP
+\fBTK_CONFIG_MM\fR
+The value must specify a screen distance in one of the forms acceptable
+to \fBTk_GetScreenMM\fR.
+The string is converted to double-precision floating-point distance
+in millimeters and the value is stored in the target.
+.TP
+\fBTK_CONFIG_PIXELS\fR
+The value must specify screen units in one of the forms acceptable
+to \fBTk_GetPixels\fR.
+The string is converted to an integer distance in pixels and the
+value is stored in the target.
+.TP
+\fBTK_CONFIG_RELIEF\fR
+The value must be an ASCII string identifying a relief in a form
+suitable for passing to \fBTk_GetRelief\fR.  The value is converted
+to an integer relief value by calling \fBTk_GetRelief\fR and the result
+is stored in the target.
+.TP
+\fBTK_CONFIG_STRING\fR
+A copy
+of the value is made by allocating memory space with
+\fBmalloc\fR and copying the value into the dynamically-allocated
+space.  A pointer to the new string is stored in the target.
+If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target will be set to NULL.
+If the previous value of the target wasn't NULL, then it is
+freed by passing it to \fBfree\fR.
+.TP
+\fBTK_CONFIG_SYNONYM\fR
+This \fItype\fR value identifies special entries in \fIspecs\fR that
+are synonyms for other entries.  If an \fIargv\fR value matches the
+\fIargvName\fR of a TK_CONFIG_SYNONYM entry, the entry isn't used
+directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR
+for another entry whose \fIargvName\fR is the same as the \fIdbName\fR
+field in the TK_CONFIG_SYNONYM entry;  this new entry is used just
+as if its \fIargvName\fR had matched the \fIargv\fR value.  The
+synonym mechanism allows multiple \fIargv\fR values to be used for
+a single configuration option, such as ``\-background'' and ``\-bg''.
+.TP
+\fBTK_CONFIG_UID\fR
+The value is translated to a \fBTk_Uid\fR
+(by passing it to \fBTk_GetUid\fR).  The resulting value
+is stored in the target.
+If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR and the value
+is an empty string then the target will be set to NULL.
+.TP
+\fBTK_CONFIG_WINDOW\fR
+The value must be a window path name.  It is translated to a
+\fBTk_Window\fR token and the token is stored in the target.
+
+.SH "GROUPED ENTRIES"
+.PP
+In some cases it is useful to generate multiple resources from
+a single configuration value.  For example, a color name might
+be used both to generate the background color for a widget (using
+TK_CONFIG_COLOR) and to generate a 3-D border to draw around the
+widget (using TK_CONFIG_BORDER).  In cases like this it is possible
+to specify that several consecutive entries in \fIspecs\fR are to
+be treated as a group.  The first entry is used to determine a value
+(using its \fIargvName\fR, \fIdbName\fR,
+\fIdbClass\fR, and \fIdefValue\fR fields).  The value will be processed
+several times (one for each entry in the group), generating multiple
+different resources and modifying multiple targets within \fIwidgRec\fR.
+Each of the entries after the first must have a NULL value in its
+\fIargvName\fR field;  this indicates that the entry is to be grouped
+with the entry that precedes it.  Only the \fItype\fR and \fIoffset\fR
+fields are used from these follow-on entries.
+
+.SH "FLAGS"
+.PP
+The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used
+in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR
+to provide additional control over the processing of configuration
+options.  These values are used in three different ways as
+described below.
+.PP
+First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has
+the TK_CONFIG_ARGV_ONLY bit set (i.e., \fIflags\fR | TK_CONFIG_ARGV_ONLY != 0),
+then the option database and
+\fIdefValue\fR fields are not used.  In this case, if an entry in
+\fIspecs\fR doesn't match a field in \fIargv\fR then nothing happens:
+the corresponding target isn't modified.  This feature is useful
+when the goal is to modify certain configuration options while
+leaving others in their current state, such as when a \fBconfigure\fR
+widget command is being processed.
+.PP
+Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used
+to control the processing of that entry.  Each \fIspecFlags\fR
+field may consists of an OR-ed combination of the following values:
+.TP
+\fBTK_CONFIG_COLOR_ONLY\fR
+If this bit is set then the entry will only be considered if the
+display for \fItkwin\fR has more than one bit plane.  If the display
+is monochromatic then this \fIspecs\fR entry will be ignored.
+.TP
+\fBTK_CONFIG_MONO_ONLY\fR
+If this bit is set then the entry will only be considered if the
+display for \fItkwin\fR has exactly one bit plane.  If the display
+is not monochromatic then this \fIspecs\fR entry will be ignored.
+.TP
+\fBTK_CONFIG_NULL_OK\fR
+This bit is only relevant for some types of entries (see the
+descriptions of the various entry types above).
+If this bit is set, it indicates that an empty string value
+for the field is acceptable and if it occurs then the
+target should be set to NULL or \fBNone\fR, depending
+on the type of the target.
+This flag is typically used to allow a
+feature to be turned off entirely, e.g. set a cursor value to
+\fBNone\fR so that a window simply inherits its parent's cursor.
+If this bit isn't set then empty strings are processed as strings,
+which generally results in an error.
+.TP
+\fBTK_CONFIG_DONT_SET_DEFAULT\fR
+If this bit is one, it means that the \fIdefValue\fR field of the
+entry should only be used for returning the default value in
+\fBTk_ConfigureInfo\fR.
+In calls to \fBTk_ConfigureWidget\fR no default will be supplied
+for entries with this flag set;  it is assumed that the
+caller has already supplied a default value in the target location.
+This flag provides a performance optimization where it is expensive
+to process the default string:  the client can compute the default
+once, save the value, and provide it before calling
+\fBTk_ConfigureWidget\fR.
+.TP
+\fBTK_CONFIG_OPTION_SPECIFIED\fR
+This bit is set and cleared by \fBTk_ConfigureWidget\fR.  Whenever
+\fBTk_ConfigureWidget\fR returns, this bit will be set in all the
+entries where a value was specified in \fIargv\fR.
+It will be zero in all other entries.
+This bit provides a way for clients to determine which values
+actually changed in a call to \fBTk_ConfigureWidget\fR.
+.PP
+The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically
+used to specify different default values for
+monochrome and color displays.  This is done by creating two
+entries in \fIspecs\fR that are identical except for their
+\fIdefValue\fR and \fIspecFlags\fR fields.  One entry should have
+the value TK_CONFIG_MONO_ONLY in its \fIspecFlags\fR and the
+default value for monochrome displays in its \fIdefValue\fR;  the
+other entry entry should have the value TK_CONFIG_COLOR_ONLY in
+its \fIspecFlags\fR and the appropriate \fIdefValue\fR for
+color displays.
+.PP
+Third, it is possible to use \fIflags\fR and \fIspecFlags\fR
+together to selectively disable some entries.  This feature is
+not needed very often.  It is useful in cases where several
+similar kinds of widgets are implemented in one place.  It allows
+a single \fIspecs\fR table to be created with all the configuration
+options for all the widget types.  When processing a particular
+widget type, only entries relevant to that type will be used.  This
+effect is achieved by setting the high-order bits (those in positions
+equal to or greater than TK_CONFIG_USER_BIT) in \fIspecFlags\fR
+values or in \fIflags\fR.  In order for a particular entry in
+\fIspecs\fR to be used, its high-order bits must match exactly
+the high-order bits of the \fIflags\fR value passed to
+\fBTk_ConfigureWidget\fR.  If a \fIspecs\fR table is being used
+for N different widget types, then N of the high-order bits will
+be used.  Each \fIspecs\fR entry will have one of more of those
+bits set in its \fIspecFlags\fR field to indicate the widget types
+for which this entry is valid.  When calling \fBTk_ConfigureWidget\fR,
+\fIflags\fR will have a single one of these bits set to select the
+entries for the desired widget type.  For a working example of
+this feature, see the code in tkButton.c.
+
+.SH TK_OFFSET
+.PP
+The \fBTk_Offset\fR macro is provided as a safe way of generating
+the \fIoffset\fR values for entries in Tk_ConfigSpec structures.
+It takes two arguments:  the name of a type of record, and the
+name of a field in that record.  It returns the byte offset of
+the named field in records of the given type.
+
+.SH TK_CONFIGUREINFO
+.PP
+The \fBTk_ConfigureInfo\fR procedure may be used to obtain
+information about one or all of the options for a given widget.
+Given a token for a window (\fItkwin\fR), a table describing the
+configuration options for a class of widgets (\fIspecs\fR), a
+pointer to a widget record containing the current information for
+a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument,
+\fBTk_ConfigureInfo\fR generates a string describing all of the
+configuration options for the window.  The string is placed
+in \fIinterp->result\fR.  Under normal circumstances
+it returns TCL_OK;  if an error occurs then it returns TCL_ERROR
+and \fIinterp->result\fR contains an error message.
+.PP
+If \fIargvName\fR is NULL, then the value left in
+\fIinterp->result\fR by \fBTk_ConfigureInfo\fR
+consists of a list of one or more entries, each of which describes
+one configuration option (i.e. one entry in \fIspecs\fR).  Each
+entry in the list will contain either two or five values.  If the
+corresponding entry in \fIspecs\fR has type TK_CONFIG_SYNONYM, then
+the list will contain two values:  the \fIargvName\fR for the entry
+and the \fIdbName\fR (synonym name).  Otherwise the list will contain
+five values:  \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR,
+and current value.  The current value is computed from the appropriate
+field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR.
+.PP
+If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL,
+then it indicates a single option, and information is returned only
+for that option.  The string placed in \fIinterp->result\fR will be
+a list containing two or five values as described above;  this will
+be identical to the corresponding sublist that would have been returned
+if \fIargvName\fR had been NULL.
+.PP
+The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict
+the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR.
+
+.SH TK_CONFIGUREVALUE
+.PP
+\fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR;
+instead of returning a list of values, it just returns the current value
+of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL).
+The value is returned in \fIinterp->result\fR and TCL_OK is
+normally returned as the procedure's result.
+If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is
+not a valid option name), TCL_ERROR is returned and an error message
+is left in \fIinterp->result\fR.
+This procedure is typically called to implement \fBcget\fR widget
+commands.
+
+.SH TK_FREEOPTIONS
+.PP
+The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup
+to release all of the resources associated with configuration options.
+It scans through \fIspecs\fR and for each entry corresponding to a
+resource that must be explicitly freed (e.g. those with
+type TK_CONFIG_COLOR), it frees the resource in the widget record.
+If the field in the widget record doesn't refer to a resource (e.g.
+it contains a null pointer) then no resource is freed for that
+entry.
+After freeing a resource, \fBTk_FreeOptions\fR sets the
+corresponding field of the widget record to null.
+
+.SH "CUSTOM OPTION TYPES"
+.PP
+Applications can extend the built-in configuration types with additional
+configuration types by writing procedures to parse and print options
+of the a type and creating a structure pointing to those procedures:
+.CS
+typedef struct Tk_CustomOption {
+	Tk_OptionParseProc *\fIparseProc\fR;
+	Tk_OptionPrintProc *\fIprintProc\fR;
+	ClientData \fIclientData\fR;
+} Tk_CustomOption;
+
+typedef int Tk_OptionParseProc(
+	ClientData \fIclientData\fR,
+	Tcl_Interp *\fIinterp\fR,
+	Tk_Window \fItkwin\fR,
+	char *\fIvalue\fR,
+	char *\fIwidgRec\fR,
+	int \fIoffset\fR);
+
+typedef char *Tk_OptionPrintProc(
+	ClientData \fIclientData\fR,
+	Tk_Window \fItkwin\fR,
+	char *\fIwidgRec\fR,
+	int \fIoffset\fR,
+	Tcl_FreeProc **\fIfreeProcPtr\fR);
+.CE
+The Tk_CustomOption structure contains three fields, which are pointers
+to the two procedures and a \fIclientData\fR value to be passed to those
+procedures when they are invoked.  The \fIclientData\fR value typically
+points to a structure containing information that is needed by the
+procedures when they are parsing and printing options.
+.PP
+The \fIparseProc\fR procedure is invoked by
+\fBTk_ConfigureWidget\fR to parse a string and store the resulting
+value in the widget record.
+The \fIclientData\fR argument is a copy of the \fIclientData\fR
+field in the Tk_CustomOption structure.
+The \fIinterp\fR argument points to a Tcl interpreter used for
+error reporting.  \fITkwin\fR is a copy of the \fItkwin\fR argument
+to \fBTk_ConfigureWidget\fR.  The \fIvalue\fR argument is a string
+describing the value for the option;  it could have been specified
+explicitly in the call to \fBTk_ConfigureWidget\fR or it could
+come from the option database or a default.
+\fIValue\fR will never be a null pointer but it may point to
+an empty string.
+\fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to
+\fBTk_ConfigureWidget\fR;  it points to the start of the widget
+record to modify.
+The last argument, \fIoffset\fR, gives the offset in bytes from the start
+of the widget record to the location where the option value is to
+be placed.  The procedure should translate the string to whatever
+form is appropriate for the option and store the value in the widget
+record.  It should normally return TCL_OK, but if an error occurs
+in translating the string to a value then it should return TCL_ERROR
+and store an error message in \fIinterp->result\fR.
+.PP
+The \fIprintProc\fR procedure is called
+by \fBTk_ConfigureInfo\fR to produce a string value describing an
+existing option.
+Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR
+arguments all have the same meaning as for Tk_OptionParseProc
+procedures.
+The \fIprintProc\fR procedure should examine the option whose value
+is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing
+that option, and return a pointer to the string.
+If the string is stored in dynamically-allocated memory, then
+the procedure must set \fI*freeProcPtr\fR to the address of
+a procedure to call to free the string's memory;  \fBTk_ConfigureInfo\fR
+will call this procedure when it is finished with the string.
+If the result string is stored in static memory then \fIprintProc\fR
+need not do anything with the \fIfreeProcPtr\fR argument.
+.PP
+Once \fIparseProc\fR and \fIprintProc\fR have been defined and a
+Tk_CustomOption structure has been created for them, options of this
+new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR
+fields are TK_CONFIG_CUSTOM and whose \fIcustomPtr\fR fields point
+to the Tk_CustomOption structure.
+
+.SH EXAMPLES
+.PP
+Although the explanation of \fBTk_ConfigureWidget\fR is fairly
+complicated, its actual use is pretty straightforward.
+The easiest way to get started is to copy the code
+from an existing widget.
+The library implementation of frames
+(tkFrame.c) has a simple configuration table, and the library
+implementation of buttons (tkButton.c) has a much more complex
+table that uses many of the fancy \fIspecFlags\fR mechanisms.
+
+.SH KEYWORDS
+anchor, bitmap, boolean, border, cap style, color, configuration options,
+cursor, custom, double, font, integer, join style, justify, millimeters,
+pixels, relief, synonym, uid