通讯编程

开发平台：
Visual C++

SetOptions.3：源码内容
							'"
'" Copyright (c) 1998 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: SetOptions.3,v 1.8 2000/10/01 21:31:35 ericm Exp $
'" 
.so man.macros
.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue,  Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset - process configuration options
.SH SYNOPSIS
.nf
fB#include <tk.h>fR
.sp
Tk_OptionTable
fBTk_CreateOptionTable(fIinterp, templatePtrfB)fR
.sp
fBTk_DeleteOptionTable(fIoptionTablefB)fR
.sp
int
fBTk_InitOptions(fIinterp, recordPtr, optionTable, tkwinfB)fR
.sp
int
fBTk_SetOptions(fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtrfB)fR
.sp
fBTk_FreeSavedOptions(fIsavedPtrfB)fR
.sp
fBTk_RestoreSavedOptions(fIsavedPtrfB)fR
.sp
Tcl_Obj *
fBTk_GetOptionValue(fIinterp, recordPtr, optionTable, namePtr, tkwinfB)fR
.sp
Tcl_Obj *
fBTk_GetOptionInfo(fIinterp, recordPtr, optionTable, namePtr, tkwinfB)fR
.sp
fBTk_FreeConfigOptions(fIrecordPtr, optionTable, tkwinfB)fR
.sp
int
fBTk_Offset(fItype, fieldfB)fR
.SH ARGUMENTS
.AS Tk_SavedOptions "*CONST objv[]" in/out
.AP Tcl_Interp *interp in
A Tcl interpreter.  Most procedures use this only for returning error
messages; if it is NULL then no error messages are returned.  For
fBTk_CreateOptionTablefR the value cannot be NULL; it gives the
interpreter in which the option table will be used.
.AP Tk_OptionSpec *templatePtr in
Points to an array of static information that describes the configuration
options that are supported.  Used to build a Tk_OptionTable.  The information
pointed to by this argument must exist for the lifetime of the Tk_OptionTable.
.AP Tk_OptionTable optionTable in
Token for an option table.  Must have been returned by a previous call
to fBTk_CreateOptionTablefR.
.AP char *recordPtr in/out
Points to structure in which values of configuration options are stored;
fields of this record are modified by procedures such as fBTk_SetOptionsfR
and read by procedures such as fBTk_GetOptionValuefR.
.AP Tk_Window tkwin in
For options such as TK_OPTION_COLOR, this argument indicates
the window in which the option will be used.  If fIoptionTablefR uses
no window-dependent options, then a NULL value may be supplied for
this argument.
.AP int objc in
Number of values in fIobjvfR.
.AP Tcl_Obj "*CONST objv[]" in
Command-line arguments for setting configuring options.
.AP Tk_SavedOptions *savePtr out
If not NULL, the structure pointed to by this argument is filled
in with the old values of any options that were modified and old
values are restored automatically if an error occurs in fBTk_SetOptionsfR.
.AP int *maskPtr out
If not NULL, the word pointed to by fImaskPtrfR is filled in with the
bit-wise OR of the fItypeMaskfR fields for the options that
were modified.
.AP Tk_SavedOptions *savedPtr in/out
Points to a structure previously filled in by fBTk_SetOptionsfR with
old values of modified options.
.AP Tcl_Obj *namePtr in
The value of this object is the name of a particular option.  If NULL
is passed to fBTk_GetOptionInfofR then information is returned for
all options.  Must not be NULL when fBTk_GetOptionValuefR is called.
.AP "type name" type in
The name of the type of a record.
.AP "field name" field in
The name of a field in records of type fItypefR.
.BE
.SH DESCRIPTION
.PP
These procedures handle most of the details of parsing configuration
options such as those for Tk widgets.  Given a description of what
options are supported, these procedures handle all the details of
parsing options and storing their values into a C structure associated
with the widget or object. The procedures were designed primarily for
widgets in Tk, but they can also be used for other kinds of objects that
have configuration options.  In the rest of this manual page ``widget'' will
be used to refer to the object whose options are being managed; in
practice the object may not actually be a widget.  The term ``widget
record'' is used to refer to the C-level structure in
which information about a particular widget or object is stored.
.PP
Note: the easiest way to learn how to use these procedures is to
look at a working example.  In Tk, the simplest example is the code
that implements the button family of widgets, which is an fBtkButton.cfR.
Other examples are in fBtkSquare.cfR and fBtkMenu.cfR.
.PP
In order to use these procedures, the code that implements the widget
must contain a static array of Tk_OptionSpec structures. This is a
template that describes the various options supported by that class of
widget; there is a separate template for each kind of widget.  The
template contains information such as the name of each option, its type,
its default value, and where the value of the option is stored in the
widget record.  See TEMPLATES below for more detail.
.PP
In order to process configuration options efficiently, the static
template must be augmented with additional information that is available
only at runtime.  The procedure fBTk_CreateOptionTablefR creates this
dynamic information from the template and returns a Tk_OptionTable token
that describes both the static and dynamic information.  All of the
other procedures, such as fBTk_SetOptionsfR, take a Tk_OptionTable
token as argument.  Typically, fBTk_CreateOptionTablefR is called the
first time that a widget of a particular class is created and the
resulting Tk_OptionTable is used in the future for all widgets of that
class.  A Tk_OptionTable may be used only in a single interpreter, given
by the fIinterpfR argument to fBTk_CreateOptionTablefR.  When an
option table is no longer needed fBTk_DeleteOptionTablefR should be
called to free all of its resources.  All of the option tables
for a Tcl interpreter are freed automatically if the interpreter is deleted.
.PP
fBTk_InitOptionsfR is invoked when a new widget is created to set
the default values for all of the widget's configuration options.
fBTk_InitOptionsfR is passed a token for an option table (fIoptionTablefR)
and a pointer to a widget record (fIrecordPtrfR), which is the C
structure that holds information about this widget. fBTk_InitOptionsfR
uses the information in the option table to
choose an appropriate default for each option, then it stores the default
value directly into the widget record, overwriting any information that
was already present in the widget record.  fBTk_InitOptionsfR normally
returns TCL_OK.  If an error occurred while setting the default values
(e.g., because a default value was erroneous) then TCL_ERROR is returned
and an error message is left in fIinterpfR's result if fIinterpfR
isn't NULL.
.PP
fBTk_SetOptionsfR is invoked to modify configuration options based
on information specified in a Tcl command.  The command might be one that
creates a new widget, or a command that modifies options on an existing
widget.  The fIobjcfR and fIobjvfR arguments describe the
values of the arguments from the Tcl command.  fIObjvfR must contain
an even number of objects: the first object of each pair gives the name of
an option and the second object gives the new value for that option.
fBTk_SetOptionsfR looks up each name in fIoptionTablefR, checks that
the new value of the option conforms to the type in fIoptionTablefR,
and stores the value of the option into the widget record given by
fIrecordPtrfR.  fBTk_SetOptionsfR normally returns TCL_OK.  If
an error occurred (such as an unknown option name or an illegal option
value) then TCL_ERROR is returned and an error message is left in
fIinterpfR's result if fIinterpfR isn't NULL.
.PP
fBTk_SetOptionsfR has two additional features.  First, if the
fImaskPtrfR argument isn't NULL then it points to an integer
value that is filled in with information about the options that were
modified.  For each option in the template passed to
fBTk_CreateOptionTablefR there is a fItypeMaskfR field.  The
bits of this field are defined by the code that implements the widget;
for example, each bit might correspond to a particular configuration option.
Alternatively, bits might be used functionally.  For example, one bit might
be used for redisplay: all options that affect the widget's display, such
that changing the option requires the widget to be redisplayed, might have
that bit set.  Another bit might indicate that the geometry of the widget
must be recomputed, and so on.  fBTk_SetOptionsfR OR's together the
fItypeMaskfR fields from all the options that were modified and returns
this value at *fImaskPtrfR; the caller can then use this information
to optimize itself so that, for example, it doesn't redisplay the widget
if the modified options don't affect the widget's appearance.
.PP
The second additional feature of fBTk_SetOptionsfR has to do with error
recovery.  If an error occurs while processing configuration options, this
feature makes it possible to restore all the configuration options to their
previous values.  Errors can occur either while processing options in
fBTk_SetOptionsfR or later in the caller.  In many cases the caller does
additional processing after fBTk_SetOptionsfR returns; for example, it
might use an option value to set a trace on a variable and may detect
an error if the variable is an array instead of a scalar.  Error recovery
is enabled by passing in a non-NULL value for the fIsavePtrfR argument
to fBTk_SetOptionsfR; this should be a pointer to an uninitialized
Tk_SavedOptions structure on the caller's stack.  fBTk_SetOptionsfR
overwrites the structure pointed to by fIsavePtrfR with information
about the old values of any options modified by the procedure.
If fBTk_SetOptionsfR returns successfully, the
caller uses the structure in one of two ways.  If the caller completes
its processing of the new options without any errors, then it must pass
the structure to fBTk_FreeSavedOptionsfR so that the old values can be
freed.  If the caller detects an error in its processing of the new
options, then it should pass the structure to fBTk_RestoreSavedOptionsfR,
which will copy the old values back into the widget record and free
the new values.
If fBTk_SetOptionsfR detects an error then it automatically restores
any options that had already been modified and leaves *fIsavePtrfR in
an empty state: the caller need not call either fBTk_FreeSavedOptionsfR or
fBTk_RestoreSavedOptionsfR.
If the fIsavePtrfR argument to fBTk_SetOptionsfR is NULL then
fBTk_SetOptionsfR frees each old option value immediately when it sets a new
value for the option.  In this case, if an error occurs in the third
option, the old values for the first two options cannot be restored.
.PP
fBTk_GetOptionValuefR returns the current value of a configuration option
for a particular widget.  The fInamePtrfR argument contains the name of
an option; fBTk_GetOptionValuefR uses fIoptionTablefR
to lookup the option and extract its value from the widget record
pointed to by fIrecordPtrfR, then it returns an object containing
that value.  If an error occurs (e.g., because fInamePtrfR contains an
unknown option name) then NULL is returned and an error message is left
in fIinterpfR's result unless fIinterpfR is NULL.
.PP
fBTk_GetOptionInfofR returns information about configuration options in
a form suitable for fBconfigurefR widget commands.  If the fInamePtrfR
argument is not NULL, it points to an object that gives the name of a
configuration option; fBTk_GetOptionInfofR returns an object containing
a list with five elements, which are the name of the option, the name and
class used for the option in the option database, the default value for
the option, and the current value for the option.  If the fInamePtrfR
argument is NULL, then fBTk_GetOptionInfofR returns information about
all options in the form of a list of lists; each sublist describes one
option.  Synonym options are handled differently depending on whether
fInamePtrfR is NULL: if fInamePtrfR is NULL then the sublist for
each synonym option has only two elements, which are the name of the
option and the name of the other option that it refers to; if fInamePtrfR
is non-NULL and names a synonym option then the object returned
is the five-element list
for the other option that the synonym refers to.  If an error occurs
(e.g., because fInamePtrfR contains an unknown option name) then NULL
is returned and an error message is left in fIinterpfR's result unless
fIinterpfR is NULL.
.PP
fBTk_FreeConfigOptionsfR must be invoked when a widget is deleted.
It frees all of the resources associated with any of the configuration
options defined in fIrecordPtrfR by fIoptionTablefR.
.PP
The fBTk_OffsetfR macro is provided as a safe way of generating the
fIobjOffsetfR and fIinternalOffsetfR values for entries in
Tk_OptionSpec 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 "TEMPLATES"
.PP
The array of Tk_OptionSpec structures passed to fBTk_CreateOptionTablefR
via its fItemplatePtrfR argument describes the configuration options
supported by a particular class of widgets.  Each structure specifies
one configuration option and has the following fields:
.CS
typedef struct {
	Tk_OptionType fItypefR;
	char *fIoptionNamefR;
	char *fIdbNamefR;
	char *fIdbClassfR;
	char *fIdefValuefR;
	int fIobjOffsetfR;
	int fIinternalOffsetfR;
	int fIflagsfR;
	ClientData fIclientDatafR;
	int fItypeMaskfR;
} Tk_OptionSpec;
.CE
The fItypefR field indicates what kind of configuration option this is
(e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for
an integer value).  fITypefR determines how the
value of the option is parsed (more on this below).
The fIoptionNamefR field is a string such as fB-fontfR or fB-bgfR;
it is the name used for the option in Tcl commands and passed to
procedures via the fIobjcfR or fInamePtrfR arguments.
The fIdbNamefR and fIdbClassfR fields are used by fBTk_InitOptionsfR
to look up a default value for this option in the option database; if
fIdbNamefR is NULL then the option database is not used by
fBTk_InitOptionsfR for this option.  The fIdefValuefR field
specifies a default value for this configuration option if no
value is specified in the option database.  The fIobjOffsetfR and
fIinternalOffsetfR fields indicate where to store the value of this
option in widget records (more on this below); values for the fIobjOffsetfR
and fIinternalOffsetfR fields should always be generated with the
fBTk_OffsetfR macro.
The fIflagsfR field contains additional information
to control the processing of this configuration option (see below
for details).
fIClientDatafR provides additional type-specific data needed
by certain types.  For instance, for TK_OPTION_COLOR types,
fIclientDatafR is a string giving the default value to use on
monochrome displays.  See the descriptions of the different types
below for details.
The last field, fItypeMaskfR, is used by fBTk_SetOptionsfR to
return information about which options were modified; see the description
of fBTk_SetOptionsfR above for details.
.PP
When fBTk_InitOptionsfR and fBTk_SetOptionsfR store the value of an
option into the widget record, they can do it in either of two ways.
If the fIobjOffsetfR field of the Tk_OptionSpec is greater than
or equal to zero, then the value of the option is stored as a
(Tcl_Obj *) at the location in the widget record given by fIobjOffsetfR.
If the fIinternalOffsetfR field of the Tk_OptionSpec is
greater than or equal to zero, then the value of the option is stored
in a type-specific internal form at the location in the widget record
given by fIinternalOffsetfR.  For example, if the option's type is
TK_OPTION_INT then the internal form is an integer.  If the
fIobjOffsetfR or fIinternalOffsetfR field is negative then the
value is not stored in that form.  At least one of the offsets must be
greater than or equal to zero.
.PP
The fIflagsfR field consists of one or more bits ORed together.  At
present only a single flag is supported: TK_OPTION_NULL_OK.  If
this bit is set for an option then an empty string will be accepted as
the value for the option and the resulting internal form will be a
NULL pointer, a zero value, or fBNonefR, depending on the type of
the option.  If the flag is not set then empty strings will result
in errors.
TK_OPTION_NULL_OK 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.
Not all option types support the TK_OPTION_NULL_OK
flag; for those that do, there is an explicit indication of that fact
in the descriptions below.
.PP
The fItypefR field of each Tk_OptionSpec structure determines
how to parse the value of that configuration option. The
legal value for fItypefR, and the corresponding actions, are
described below.  If the type requires a fItkwinfR value to be
passed into procedures like fBTk_SetOptionsfR, or if it uses
the fIclientDatafR field of the Tk_OptionSpec, then it is indicated
explicitly; if not mentioned, the type requires neither fItkwinfR
nor fIclientDatafR.
.TP
fBTK_OPTION_ANCHORfR
The value must be a standard anchor position such as fBnefR or
fBcenterfR.  The internal form is a Tk_Anchor value like the ones
returned by fBTk_GetAnchorFromObjfR.
.TP
fBTK_OPTION_BITMAPfR
The value must be a standard Tk bitmap name. The internal form is a
Pixmap token like the ones returned by fBTk_AllocBitmapFromObjfR.
This option type requires fItkwinfR to be supplied to procedures
such as fBTk_SetOptionsfR, and it supports the TK_OPTION_NULL_OK flag.
.TP
fBTK_OPTION_BOOLEANfR
The value must be a standard boolean value such as fBtruefR or
fBnofR.  The internal form is an integer with value 0 or 1.
.TP
fBTK_OPTION_BORDERfR
The value must be a standard color name such as fBredfR or fB#ff8080fR.
The internal form is a Tk_3DBorder token like the ones returned
by fBTk_Alloc3DBorderFromObjfR.
This option type requires fItkwinfR to be supplied to procedures
such as fBTk_SetOptionsfR, and it supports the TK_OPTION_NULL_OK flag.
.TP
fBTK_OPTION_COLORfR
The value must be a standard color name such as fBredfR or fB#ff8080fR.
The internal form is an (XColor *) token like the ones returned by
fBTk_AllocColorFromObjfR.
This option type requires fItkwinfR to be supplied to procedures
such as fBTk_SetOptionsfR, and it supports the TK_OPTION_NULL_OK flag.
.TP
fBTK_OPTION_CURSORfR
The value must be a standard cursor name such as fBcrossfR or fB@foofR.
The internal form is a Tk_Cursor token like the ones returned by
fBTk_AllocCursorFromObjfR.
This option type requires fItkwinfR to be supplied to procedures
such as fBTk_SetOptionsfR, and when the option is set the cursor
for the window is changed by calling fBXDefineCursorfR.  This
option type also supports the TK_OPTION_NULL_OK flag.
.TP
fBTK_OPTION_CUSTOMfR
This option allows applications to define new option types.  The
clientData field of the entry points to a structure defining the new
option type.  See the section CUSTOM OPTION TYPES below for details.
.TP
fBTK_OPTION_DOUBLEfR
The string value must be a floating-point number in
the format accepted by fBstrtolfR.  The internal form is a C
fBdoublefR value.  This option type supports the TK_OPTION_NULL_OK
flag; if a NULL value is set, the internal representation is set to zero.
.TP
fBTK_OPTION_ENDfR
Marks the end of the template.  There must be a Tk_OptionSpec structure
with fItypefR TK_OPTION_END at the end of each template.  If the
fIclientDatafR field of this structure isn't NULL, then it points to
an additional array of Tk_OptionSpec's, which is itself terminated by
another TK_OPTION_END entry.  Templates may be chained arbitrarily
deeply.  This feature allows common options to be shared by several
widget classes.
.TP
fBTK_OPTION_FONTfR
The value must be a standard font name such as fBTimes 16fR.
The internal form is a Tk_Font handle like the ones returned by
fBTk_AllocFontFromObjfR.
This option type requires fItkwinfR to be supplied to procedures
such as fBTk_SetOptionsfR, and it supports the TK_OPTION_NULL_OK flag.
.TP
fBTK_OPTION_INTfR
The string value must be an integer in the format accepted by
fBstrtolfR (e.g. fB0fR and fB0xfR prefixes may be used to
specify octal or hexadecimal numbers, respectively).  The internal
form is a C fBintfR value.
.TP
fBTK_OPTION_JUSTIFYfR
The value must be a standard justification value such as fBleftfR.
The internal form is a Tk_Justify like the values returned by
fBTk_GetJustifyFromObjfR.
.TP
fBTK_OPTION_PIXELSfR
The value must specify a screen distance such as fB2ifR or fB6.4fR.
The internal form is an integer value giving a
distance in pixels, like the values returned by
fBTk_GetPixelsFromObjfR.  Note: if the fIobjOffsetfR field isn't
used then information about the original value of this option will be lost.
See fBOBJOFFSET VS. INTERNALOFFSETfR below for details.  This option
type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the
internal representation is set to zero.
.TP
fBTK_OPTION_RELIEFfR
The value must be standard relief such as fBraisedfR.
The internal form is an integer relief value such as
TK_RELIEF_RAISED.  This option type supports the TK_OPTION_NULL_OK
flag; if the empty string is specified as the value for the option,
the integer relief value is set to TK_RELIEF_NULL.
.TP
fBTK_OPTION_STRINGfR
The value may be any string.  The internal form is a (char *) pointer
that points to a dynamically allocated copy of the value.
This option type supports the TK_OPTION_NULL_OK flag.
.TP
fBTK_OPTION_STRING_TABLEfR
For this type, fIclientDatafR is a pointer to an array of strings
suitable for passing to fBTcl_GetIndexFromObjfR.  The value must
be one of the strings in the table, or a unique abbreviation of
one of the strings.  The internal form is an integer giving the index
into the table of the matching string, like the return value
from fBTcl_GetStringFromObjfR. 
.TP
fBTK_OPTION_SYNONYMfR
This type is used to provide alternative names for an option (for
example, fB-bgfR is often used as a synonym for fB-backgroundfR).
The fBclientDatafR field is a (char *) pointer that gives
the name of another option in the same table.  Whenever the
synonym option is used, the information from the other option
will be used instead.
.TP
fBTK_OPTION_WINDOWfR
The value must be a window path name.  The internal form is a
fBTk_WindowfR token for the window.
This option type requires fItkwinfR to be supplied to procedures
such as fBTk_SetOptionsfR (in order to identify the application),
and it supports the TK_OPTION_NULL_OK flag.
.SH "STORAGE MANAGEMENT ISSUES"
.PP
If a field of a widget record has its offset stored in the fIobjOffsetfR
or fIinternalOffsetfR field of a Tk_OptionSpec structure then the
procedures described here will handle all of the storage allocation and
resource management issues associated with the field.  When the value
of an option is changed, fBTk_SetOptionsfR (or fBTk_FreeSavedOptionsfR)
will automatically free any resources associated with the old value, such as
Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for
TK_OPTION_STRING options.  For an option stored as an object using the
fIobjOffsetfR field of a Tk_OptionSpec, the widget record shares the
object pointed to by the fIobjvfR value from the call to
fBTk_SetOptionsfR.  The reference count for this object is incremented
when a pointer to it is stored in the widget record and decremented when
the option is modified.  When the widget is deleted
fBTk_FreeConfigOptionsfR should be invoked; it will free the resources
associated with all options and decrement reference counts for any
objects.
.PP
However, the widget code is responsible for storing NULL or fBNonefR in
all pointer and token fields before invoking fBTk_InitOptionsfR.
This is needed to allow proper cleanup in the rare case where
an error occurs in fBTk_InitOptionsfR.
.SH "OBJOFFSET VS. INTERNALOFFSET"
.PP
In most cases it is simplest to use the fIinternalOffsetfR field of
a Tk_OptionSpec structure and not the fIobjOffsetfR field.  This
makes the internal form of the value immediately available to the
widget code so the value doesn't have to be extracted from an object
each time it is used.  However, there are two cases where the
fIobjOffsetfR field is useful.  The first case is for
TK_OPTION_PIXELS options.  In this case, the internal form is
an integer pixel value that is valid only for a particular screen.
If the value of the option is retrieved, it will be returned as a simple
number.  For example, after the command fB.b configure -borderwidth 2mfR,
the command fB.b configure -borderwidthfR might return 7, which is the
integer pixel value corresponding to fB2mfR.  Unfortunately, this loses
the original screen-independent value.  Thus for TK_OPTION_PIXELS options
it is better to use the fIobjOffsetfR field.  In this case the original
value of the option is retained in the object and can be returned when
the option is retrieved.  In most cases it is convenient to use the
fIinternalOffsetfR field field as well, so that the integer value is
immediately available for use in the widget code (alternatively,
fBTk_GetPixelsFromObjfR can be used to extract the integer value from
the object whenever it is needed).  Note: the problem of losing information
on retrievals exists only for TK_OPTION_PIXELS options.
.PP
The second reason to use the fIobjOffsetfR field is in order to
implement new types of options not supported by these procedures.
To implement a new type of option, you can use TK_OPTION_STRING as
the type in the Tk_OptionSpec structure and set the fIobjOffsetfR field
but not the fIinternalOffsetfR field.  Then, after calling
fBTk_SetOptionsfR, convert the object to internal form yourself.
.SH "CUSTOM OPTION TYPES"
.PP
Applications can extend the built-in configuration types with
additional configuration types by writing procedures to parse, print,
free, and restore saved copies of the type and creating a structure
pointing to those procedures:
.CS
typedef struct Tk_ObjCustomOption {
	char *name;
	Tk_CustomOptionSetProc *fIsetProcfR;
	Tk_CustomOptionGetProc *fIgetProcfR;
	Tk_CustomOptionRestoreProc *fIrestoreProcfR;
	Tk_CustomOptionFreeProc *fIfreeProcfR;
	ClientData fIclientDatafR;
} Tk_ObjCustomOption;
typedef int Tk_CustomOptionSetProc(
	ClientData fIclientDatafR,
	Tcl_Interp *fIinterpfR, 
	Tk_Window fItkwinfR, 
	Tcl_Obj **fIvaluePtrfR,
	char *fIrecordPtrfR,
	int fIinternalOffsetfR,
	char *fIsaveInternalPtrfR, 
	int fIflagsfR);
typedef Tcl_Obj *Tk_CustomOptionGetProc(
	ClientData fIclientDatafR,
	Tk_Window fItkwinfR, 
	char *fIrecordPtrfR,
	int fIinternalOffsetfR);
typedef void Tk_CustomOptionRestoreProc(
	ClientData fIclientDatafR,
	Tk_Window fItkwinfR, 
	char *fIinternalPtrfR, 
	char *fIsaveInternalPtrfR);
typedef void Tk_CustomOptionFreeProc(
	ClientData fIclientDatafR,
	Tk_Window fItkwinfR, 
	char *fIinternalPtrfR);
.CE
.PP
The Tk_ObjCustomOption structure contains six fields: a name
for the custom option type; pointers to the four 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.  fIRestoreProcfR and fIfreeProcfR
may be NULL, indicating that no function should be called for those
operations.
.PP
The fIsetProcfR procedure is invoked by fBTk_SetOptionsfR to
convert a Tcl_Obj into an internal representation and store the
resulting value in the widget record.  The arguments are:
.RS
.TP
fIclientDatafR
A copy of the fIclientDatafR field in the Tk_ObjCustomOption
structure.
.TP
fIinterpfR
A pointer to a Tcl interpreter, used for error reporting.
.TP
fITkwinfR
A copy of the fItkwinfR argument to fBTk_SetOptionsfR
.TP
fIvaluePtrfR
A pointer to a reference to a Tcl_Obj describing the new value for the
option; it could have been specified explicitly in the call to
fBTk_SetOptionsfR or it could come from the option database or a
default.  If the objOffset for the option is non-negative (the option
value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj
pointer referenced by fIvaluePtrfR is the pointer that will be
stored at the objOffset for the option.  fISetProcfR may modify the
value if necessary; for example, fIsetProcfR may change the value to
NULL to support the TK_OPTION_NULL_OK flag.
.TP
fIrecordPtrfR
A pointer to the start of the widget record to modify.
.TP
fIinternalOffsetfR
Offset in bytes from the start of the widget record to the location
where the internal representation of the option value is to be placed.
.TP
fIsaveInternalPtrfR
A pointer to storage allocated in a Tk_SavedOptions structure for the
internal representation of the original option value.  Before setting
the option to its new value, fIsetProcfR should set the value
referenced by fIsaveInternalPtrfR to the original value of the
option in order to support fBTk_RestoreSavedOptionsfR.
.TP
fIflagsfR
A copy of the fIflagsfR field in the Tk_OptionSpec structure for the
option
.RE
.PP
fISetProcfR returns a standard Tcl result:  TCL_OK to indicate successful
processing, or TCL_ERROR to indicate a failure of any kind.  An error
message may be left in the Tcl interpreter given by fIinterpfR in
the case of an error.
.PP
The fIgetProcfR procedure is invoked by fBTk_GetOptionValuefR and
fBTk_GetOptionInfofR to retrieve a Tcl_Obj representation of the
internal representation of an option.  The fIclientDatafR argument
is a copy of the fIclientDatafR field in the Tk_ObjCustomOption
structure.  fITkwinfR is a copy of the fItkwinfR argument to
fBTk_GetOptionValuefR or fBTk_GetOptionInfofR.  fIRecordPtrfR
is a pointer to the beginning of the widget record to query.
fIInternalOffsetfR is the offset in bytes from the beginning of the
widget record to the location where the internal representation of the
option value is stored.  fIGetProcfR must return a pointer to a
Tcl_Obj representing the value of the option.
.PP
The fIrestoreProcfR procedure is invoked by
fBTk_RestoreSavedOptionsfR to restore a previously saved internal
representation of a custom option value.  The fIclientDatafR argument
is a copy of the fIclientDatafR field in the Tk_ObjCustomOption
structure.  fITkwinfR is a copy of the fItkwinfR argument to
fBTk_GetOptionValuefR or fBTk_GetOptionInfofR.  fIInternalPtrfR
is a pointer to the location where internal representation of the
option value is stored.
fISaveInternalPtrfR is a pointer to the saved value.
fIRestoreProcfR must copy the value from fIsaveInternalPtrfR to
fIinternalPtrfR to restore the value.  fIRestoreProcfR need not
free any memory associated with either fIinternalPtrfR or
fIsaveInternalPtrfR; fIfreeProcfR will be invoked to free that
memory if necessary.  fIRestoreProcfR has no return value.
.PP
The fIfreeProcfR procedure is invoked by fBTk_SetOptionsfR and
fBTk_FreeSavedOptionsfR to free any storage allocated for the
internal representation of a custom option.  The fIclientDatafR argument
is a copy of the fIclientDatafR field in the Tk_ObjCustomOption
structure.  fITkwinfR is a copy of the fItkwinfR argument to
fBTk_GetOptionValuefR or fBTk_GetOptionInfofR.  fIInternalPtrfR
is a pointer to the location where the internal representation of the
option value is stored.  The fIfreeProcfR must free any storage
associated with the option.  fIFreeProcfR has no return value.
.SH KEYWORDS
anchor, bitmap, boolean, border, color, configuration option,
cursor, double, font, integer, justify,
pixels, relief, screen distance, synonym

						