configwidg.3

linux系统下的音频通信

\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