通讯编程

开发平台：
Visual C++

ConfigWidg.3：源码内容
							'"
'" 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.
'" 
'" RCS: @(#) $Id: ConfigWidg.3,v 1.8.2.1 2003/10/06 22:15:17 dgp Exp $
'" 
.so man.macros
.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_ConfigureWidget, 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, flagsfB)fR
.sp
int
fBTk_ConfigureInfo(fIinterp, tkwin, specs, widgRec, argvName, flagsfB)fR
.sp
int
fBTk_ConfigureValue(fIinterp, tkwin, specs, widgRec, argvName, flagsfB)fR
.sp
fBTk_FreeOptions(fIspecs, widgRec, display, flagsfB)fR
.SH ARGUMENTS
.AS Tk_ConfigSpec *widgRec in/out
.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 fIargvfR.
.AP "CONST 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_ConfigureWidgetfR 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 fIspecsfR.
.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 fItypefR.
.AP "CONST 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 fBconfigurefR 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
.VS 8.1 
.PP 
Note: fBTk_ConfigureWidgetfP should be replaced with the new
fBTcl_ObjfP based API fBTk_SetOptionsfP.  The old interface is
retained for backward compatibility.
.VE 
.PP
fBTk_ConfigureWidgetfR 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 fBconfigurefR
command is invoked for a widget.
Although intended primarily for widgets, fBTk_ConfigureWidgetfR
can be used in other situations where fIargc-argvfR 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_ConfigureWidgetfR processes
a table specifying the configuration options that are supported
(fIspecsfR) and a collection of command-line arguments (fIargcfR and
fIargvfR) to fill in fields of a record (fIwidgRecfR).
It uses the option database and defaults specified in fIspecsfR
to fill in fields of fIwidgRecfR that are not specified in fIargvfR.
fBTk_ConfigureWidgetfR normally returns the value TCL_OK; in this
case it does not modify fIinterpfR.
If an error
occurs then TCL_ERROR is returned and fBTk_ConfigureWidgetfR will
leave an error message in fIinterp->resultfR in the standard Tcl
fashion.
In the event of an error return, some of the fields of fIwidgRecfR
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_FreeOptionsfR can be called for cleanup.
.PP
The fIspecsfR 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 fItypefR;
	char *fIargvNamefR;
	char *fIdbNamefR;
	char *fIdbClassfR;
	char *fIdefValuefR;
	int fIoffsetfR;
	int fIspecFlagsfR;
	Tk_CustomOption *fIcustomPtrfR;
} Tk_ConfigSpec;
.CE
The fItypefR 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 fItypefR field indicates how to use the
value of the option (more on this below).
The fIargvNamefR field is a string such as ``-font'' or ``-bg'',
which is compared with the values in fIargvfR (if fIargvNamefR is
NULL it means this is a grouped entry;  see GROUPED ENTRIES below).  The
fIdbNamefR and fIdbClassfR fields are used to look up a value
for this option in the option database.  The fIdefValuefR field
specifies a default value for this configuration option if no
value is specified in either fIargvfR or the option database.
fIOffsetfR indicates where in fIwidgRecfR to store information
about this option, and fIspecFlagsfR contains additional information
to control the processing of this configuration option (see FLAGS
below).
The last field, fIcustomPtrfR, is only used if fItypefR is
TK_CONFIG_CUSTOM;  see CUSTOM OPTION TYPES below.
.PP
fBTk_ConfigureWidgetfR first processes fIargvfR to see which
(if any) configuration options are specified there.  fIArgvfR
must contain an even number of fields;  the first of each pair
of fields must match the fIargvNamefR of some entry in fIspecsfR
(unique abbreviations are acceptable),
and the second field of the pair contains the value for that
configuration option.  If there are entries in fIspecfR for which
there were no matching entries in fIargvfR,
fBTk_ConfigureWidgetfR uses the fIdbNamefR and fIdbClassfR
fields of the fIspecsfR 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
fIdefValuefR field of the fIspecsfR entry is used as the
value for the configuration option.  If the fIdefValuefR is
NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in
fIflagsfR, then there is no default value and this fIspecsfR entry
will be ignored if no value is specified in fIargvfR or the
option database.
.PP
Once a string value has been determined for a configuration option,
fBTk_ConfigureWidgetfR translates the string value into a more useful
form, such as a color if fItypefR is TK_CONFIG_COLOR or an integer
if fItypefR is TK_CONFIG_INT.  This value is then stored in the
record pointed to by fIwidgRecfR.  This record is assumed to
contain information relevant to the manager of the widget;  its exact
type is unknown to fBTk_ConfigureWidgetfR.  The fIoffsetfR field
of each fIspecsfR entry indicates where in fIwidgRecfR to store
the information about this configuration option.  You should use the
fBTk_OffsetfR macro to generate fIoffsetfR values (see below for
a description of fBTk_OffsetfR).  The location indicated by
fIwidgRecfR and fIoffsetfR will be referred to as the ``target''
in the descriptions below.
.PP
The fItypefR field of each entry in fIspecsfR determines what
to do with the string value of that configuration option.  The
legal values for fItypefR, and the corresponding actions, are:
.TP
fBTK_CONFIG_ACTIVE_CURSORfR
The value
must be an ASCII string identifying a cursor in a form
suitable for passing to fBTk_GetCursorfR. 
The value is converted to a fBTk_CursorfR by calling
fBTk_GetCursorfR and the result is stored in the target.
In addition, the resulting cursor is made the active cursor
for fItkwinfR by calling fBXDefineCursorfR.
If TK_CONFIG_NULL_OK is specified in fIspecFlagsfR then the value
may be an empty string, in which case the target and fItkwinfR's
active cursor will be set to fBNonefR.
If the previous value of the target
wasn't fBNonefR, then it is freed by passing it to fBTk_FreeCursorfR.
.TP
fBTK_CONFIG_ANCHORfR
The value must be an ASCII string identifying an anchor point in one of the ways
accepted by fBTk_GetAnchorfR.
The string is converted to a fBTk_AnchorfR by calling
fBTk_GetAnchorfR and the result is stored in the target.
.TP
fBTK_CONFIG_BITMAPfR
The value must be an ASCII string identifying a bitmap in a form
suitable for passing to fBTk_GetBitmapfR.  The value is converted
to a fBPixmapfR by calling fBTk_GetBitmapfR and the result
is stored in the target.
If TK_CONFIG_NULL_OK is specified in fIspecFlagsfR then the value
may be an empty string, in which case the target is set to fBNonefR.
If the previous value of the target
wasn't fBNonefR, then it is freed by passing it to fBTk_FreeBitmapfR.
.TP
fBTK_CONFIG_BOOLEANfR
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_BORDERfR
The value must be an ASCII string identifying a border color in a form
suitable for passing to fBTk_Get3DBorderfR.  The value is converted
to a (fBTk_3DBorder *fR) by calling fBTk_Get3DBorderfR and the result
is stored in the target.
If TK_CONFIG_NULL_OK is specified in fIspecFlagsfR 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_Free3DBorderfR.
.TP
fBTK_CONFIG_CAP_STYLEfR
The value must be
an ASCII string identifying a cap style in one of the ways
accepted by fBTk_GetCapStylefR.
The string is converted to an integer value corresponding
to the cap style by calling
fBTk_GetCapStylefR and the result is stored in the target.
.TP
fBTK_CONFIG_COLORfR
The value must be an ASCII string identifying a color in a form
suitable for passing to fBTk_GetColorfR.  The value is converted
to an (fBXColor *fR) by calling fBTk_GetColorfR and the result
is stored in the target.
If TK_CONFIG_NULL_OK is specified in fIspecFlagsfR then the value
may be an empty string, in which case the target will be set to fBNonefR.
If the previous value of the target
wasn't NULL, then it is freed by passing it to fBTk_FreeColorfR.
.TP
fBTK_CONFIG_CURSORfR
This option is identical to fBTK_CONFIG_ACTIVE_CURSORfR except
that the new cursor is not made the active one for fItkwinfR.
.TP
fBTK_CONFIG_CUSTOMfR
This option allows applications to define new option types.
The fIcustomPtrfR 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_DOUBLEfR
The value must be an ASCII floating-point number in
the format accepted by fBstrtolfR.  The string is converted
to a fBdoublefR value, and the value is stored in the
target.
.TP
fBTK_CONFIG_ENDfR
Marks the end of the table.  The last entry in fIspecsfR
must have this type;  all of its other fields are ignored and it
will never match any arguments.
.TP
fBTK_CONFIG_FONTfR
The value must be an ASCII string identifying a font in a form
suitable for passing to fBTk_GetFontfR.  The value is converted
to a fBTk_FontfR by calling fBTk_GetFontfR and the result
is stored in the target.
If TK_CONFIG_NULL_OK is specified in fIspecFlagsfR 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_FreeFontfR.
.TP
fBTK_CONFIG_INTfR
The value must be an ASCII integer string
in the format accepted by fBstrtolfR (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_STYLEfR
The value must be
an ASCII string identifying a join style in one of the ways
accepted by fBTk_GetJoinStylefR.
The string is converted to an integer value corresponding
to the join style by calling
fBTk_GetJoinStylefR and the result is stored in the target.
.TP
fBTK_CONFIG_JUSTIFYfR
The value must be
an ASCII string identifying a justification method in one of the
ways accepted by fBTk_GetJustifyfR.
The string is converted to a fBTk_JustifyfR by calling
fBTk_GetJustifyfR and the result is stored in the target.
.TP
fBTK_CONFIG_MMfR
The value must specify a screen distance in one of the forms acceptable
to fBTk_GetScreenMMfR.
The string is converted to double-precision floating-point distance
in millimeters and the value is stored in the target.
.TP
fBTK_CONFIG_PIXELSfR
The value must specify screen units in one of the forms acceptable
to fBTk_GetPixelsfR.
The string is converted to an integer distance in pixels and the
value is stored in the target.
.TP
fBTK_CONFIG_RELIEFfR
The value must be an ASCII string identifying a relief in a form
suitable for passing to fBTk_GetRelieffR.  The value is converted
to an integer relief value by calling fBTk_GetRelieffR and the result
is stored in the target.
.TP
fBTK_CONFIG_STRINGfR
A copy
of the value is made by allocating memory space with
fBmallocfR 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 fIspecFlagsfR 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 fBfreefR.
.TP
fBTK_CONFIG_SYNONYMfR
This fItypefR value identifies special entries in fIspecsfR that
are synonyms for other entries.  If an fIargvfR value matches the
fIargvNamefR of a TK_CONFIG_SYNONYM entry, the entry isn't used
directly. Instead, fBTk_ConfigureWidgetfR searches fIspecsfR
for another entry whose fIargvNamefR is the same as the fIdbNamefR
field in the TK_CONFIG_SYNONYM entry;  this new entry is used just
as if its fIargvNamefR had matched the fIargvfR value.  The
synonym mechanism allows multiple fIargvfR values to be used for
a single configuration option, such as ``-background'' and ``-bg''.
.TP
fBTK_CONFIG_UIDfR
The value is translated to a fBTk_UidfR
(by passing it to fBTk_GetUidfR).  The resulting value
is stored in the target.
If TK_CONFIG_NULL_OK is specified in fIspecFlagsfR and the value
is an empty string then the target will be set to NULL.
.TP
fBTK_CONFIG_WINDOWfR
The value must be a window path name.  It is translated to a
fBTk_WindowfR 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 fIspecsfR are to
be treated as a group.  The first entry is used to determine a value
(using its fIargvNamefR, fIdbNamefR,
fIdbClassfR, and fIdefValuefR fields).  The value will be processed
several times (one for each entry in the group), generating multiple
different resources and modifying multiple targets within fIwidgRecfR.
Each of the entries after the first must have a NULL value in its
fIargvNamefR field;  this indicates that the entry is to be grouped
with the entry that precedes it.  Only the fItypefR and fIoffsetfR
fields are used from these follow-on entries.
.SH "FLAGS"
.PP
The fIflagsfR argument passed to fBTk_ConfigureWidgetfR is used
in conjunction with the fIspecFlagsfR fields in the entries of fIspecsfR
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 fIflagsfR argument to fBTk_ConfigureWidgetfR has
the TK_CONFIG_ARGV_ONLY bit set (i.e., fIflagsfR | TK_CONFIG_ARGV_ONLY != 0),
then the option database and
fIdefValuefR fields are not used.  In this case, if an entry in
fIspecsfR doesn't match a field in fIargvfR 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 fBconfigurefR
widget command is being processed.
.PP
Second, the fIspecFlagsfR field of an entry in fIspecsfR may be used
to control the processing of that entry.  Each fIspecFlagsfR
field may consists of an OR-ed combination of the following values:
.TP
fBTK_CONFIG_COLOR_ONLYfR
If this bit is set then the entry will only be considered if the
display for fItkwinfR has more than one bit plane.  If the display
is monochromatic then this fIspecsfR entry will be ignored.
.TP
fBTK_CONFIG_MONO_ONLYfR
If this bit is set then the entry will only be considered if the
display for fItkwinfR has exactly one bit plane.  If the display
is not monochromatic then this fIspecsfR entry will be ignored.
.TP
fBTK_CONFIG_NULL_OKfR
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 fBNonefR, 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
fBNonefR 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_DEFAULTfR
If this bit is one, it means that the fIdefValuefR field of the
entry should only be used for returning the default value in
fBTk_ConfigureInfofR.
In calls to fBTk_ConfigureWidgetfR 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_ConfigureWidgetfR.
.TP
fBTK_CONFIG_OPTION_SPECIFIEDfR
This bit is set and cleared by fBTk_ConfigureWidgetfR.  Whenever
fBTk_ConfigureWidgetfR returns, this bit will be set in all the
entries where a value was specified in fIargvfR.
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_ConfigureWidgetfR.
.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 fIspecsfR that are identical except for their
fIdefValuefR and fIspecFlagsfR fields.  One entry should have
the value TK_CONFIG_MONO_ONLY in its fIspecFlagsfR and the
default value for monochrome displays in its fIdefValuefR;  the
other entry entry should have the value TK_CONFIG_COLOR_ONLY in
its fIspecFlagsfR and the appropriate fIdefValuefR for
color displays.
.PP
Third, it is possible to use fIflagsfR and fIspecFlagsfR
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 fIspecsfR 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 fIspecFlagsfR
values or in fIflagsfR.  In order for a particular entry in
fIspecsfR to be used, its high-order bits must match exactly
the high-order bits of the fIflagsfR value passed to
fBTk_ConfigureWidgetfR.  If a fIspecsfR table is being used
for N different widget types, then N of the high-order bits will
be used.  Each fIspecsfR entry will have one of more of those
bits set in its fIspecFlagsfR field to indicate the widget types
for which this entry is valid.  When calling fBTk_ConfigureWidgetfR,
fIflagsfR 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_OffsetfR macro is provided as a safe way of generating
the fIoffsetfR 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_ConfigureInfofR procedure may be used to obtain
information about one or all of the options for a given widget.
Given a token for a window (fItkwinfR), a table describing the
configuration options for a class of widgets (fIspecsfR), a
pointer to a widget record containing the current information for
a widget (fIwidgRecfR), and a NULL fIargvNamefR argument,
fBTk_ConfigureInfofR generates a string describing all of the
configuration options for the window.  The string is placed
in fIinterp->resultfR.  Under normal circumstances
it returns TCL_OK;  if an error occurs then it returns TCL_ERROR
and fIinterp->resultfR contains an error message.
.PP
If fIargvNamefR is NULL, then the value left in
fIinterp->resultfR by fBTk_ConfigureInfofR
consists of a list of one or more entries, each of which describes
one configuration option (i.e. one entry in fIspecsfR).  Each
entry in the list will contain either two or five values.  If the
corresponding entry in fIspecsfR has type TK_CONFIG_SYNONYM, then
the list will contain two values:  the fIargvNamefR for the entry
and the fIdbNamefR (synonym name).  Otherwise the list will contain
five values:  fIargvNamefR, fIdbNamefR, fIdbClassfR, fIdefValuefR,
and current value.  The current value is computed from the appropriate
field of fIwidgRecfR by calling procedures like fBTk_NameOfColorfR.
.PP
If the fIargvNamefR argument to fBTk_ConfigureInfofR is non-NULL,
then it indicates a single option, and information is returned only
for that option.  The string placed in fIinterp->resultfR 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 fIargvNamefR had been NULL.
.PP
The fIflagsfR argument to fBTk_ConfigureInfofR is used to restrict
the fIspecsfR entries to consider, just as for fBTk_ConfigureWidgetfR.
.SH TK_CONFIGUREVALUE
.PP
fBTk_ConfigureValuefR takes arguments similar to fBTk_ConfigureInfofR;
instead of returning a list of values, it just returns the current value
of the option given by fIargvNamefR (fIargvNamefR must not be NULL).
The value is returned in fIinterp->resultfR and TCL_OK is
normally returned as the procedure's result.
If an error occurs in fBTk_ConfigureValuefR (e.g., fIargvNamefR is
not a valid option name), TCL_ERROR is returned and an error message
is left in fIinterp->resultfR.
This procedure is typically called to implement fBcgetfR widget
commands.
.SH TK_FREEOPTIONS
.PP
The fBTk_FreeOptionsfR procedure may be invoked during widget cleanup
to release all of the resources associated with configuration options.
It scans through fIspecsfR 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_FreeOptionsfR 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 *fIparseProcfR;
	Tk_OptionPrintProc *fIprintProcfR;
	ClientData fIclientDatafR;
} Tk_CustomOption;
typedef int Tk_OptionParseProc(
	ClientData fIclientDatafR,
	Tcl_Interp *fIinterpfR,
	Tk_Window fItkwinfR,
	char *fIvaluefR,
	char *fIwidgRecfR,
	int fIoffsetfR);
typedef char *Tk_OptionPrintProc(
	ClientData fIclientDatafR,
	Tk_Window fItkwinfR,
	char *fIwidgRecfR,
	int fIoffsetfR,
	Tcl_FreeProc **fIfreeProcPtrfR);
.CE
The Tk_CustomOption structure contains three fields, which are pointers
to the two procedures and a fIclientDatafR value to be passed to those
procedures when they are invoked.  The fIclientDatafR value typically
points to a structure containing information that is needed by the
procedures when they are parsing and printing options.
.PP
The fIparseProcfR procedure is invoked by
fBTk_ConfigureWidgetfR to parse a string and store the resulting
value in the widget record.
The fIclientDatafR argument is a copy of the fIclientDatafR
field in the Tk_CustomOption structure.
The fIinterpfR argument points to a Tcl interpreter used for
error reporting.  fITkwinfR is a copy of the fItkwinfR argument
to fBTk_ConfigureWidgetfR.  The fIvaluefR argument is a string
describing the value for the option;  it could have been specified
explicitly in the call to fBTk_ConfigureWidgetfR or it could
come from the option database or a default.
fIValuefR will never be a null pointer but it may point to
an empty string.
fIRecordPtrfR is the same as the fIwidgRecfR argument to
fBTk_ConfigureWidgetfR;  it points to the start of the widget
record to modify.
The last argument, fIoffsetfR, 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->resultfR.
.PP
The fIprintProcfR procedure is called
by fBTk_ConfigureInfofR to produce a string value describing an
existing option.
Its fIclientDatafR, fItkwinfR, fIwidgRecfR, and fIoffsetfR
arguments all have the same meaning as for Tk_OptionParseProc
procedures.
The fIprintProcfR procedure should examine the option whose value
is stored at fIoffsetfR in fIwidgRecfR, 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*freeProcPtrfR to the address of
a procedure to call to free the string's memory;  fBTk_ConfigureInfofR
will call this procedure when it is finished with the string.
If the result string is stored in static memory then fIprintProcfR
need not do anything with the fIfreeProcPtrfR argument.
.PP
Once fIparseProcfR and fIprintProcfR 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 fItypefR
fields are TK_CONFIG_CUSTOM and whose fIcustomPtrfR fields point
to the Tk_CustomOption structure.
.SH EXAMPLES
.PP
Although the explanation of fBTk_ConfigureWidgetfR 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 fIspecFlagsfR mechanisms.
.SH "SEE ALSO"
Tk_SetOptions(3)
.SH KEYWORDS
anchor, bitmap, boolean, border, cap style, color, configuration options,
cursor, custom, double, font, integer, join style, justify, millimeters,
pixels, relief, synonym, uid

						