619 lines
28 KiB
Groff
619 lines
28 KiB
Groff
'\"
|
|
'\" 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
|