NAME¶
Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions -
process configuration options for widgets
SYNOPSIS¶
#include <tk.h>
int
Tk_ConfigureWidget(interp, tkwin, specs, argc, argv, widgRec, flags)
int
Tk_ConfigureInfo(interp, tkwin, specs, widgRec, argvName, flags)
int
Tk_ConfigureValue(interp, tkwin, specs, widgRec, argvName, flags)
Tk_FreeOptions(specs, widgRec, display, flags)
ARGUMENTS¶
- Tcl_Interp *interp (in)
- Interpreter to use for returning error messages.
- Tk_Window tkwin (in)
- Window used to represent widget (needed to set up X
resources).
- Tk_ConfigSpec *specs (in)
- Pointer to table specifying legal configuration options for
this widget.
- int argc (in)
- Number of arguments in argv.
- const char **argv (in)
- Command-line options for configuring widget.
- char *widgRec (in/out)
- Points to widget record structure. Fields in this structure
get modified by Tk_ConfigureWidget to hold configuration
information.
- 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 specs.
- type name type (in)
- The name of the type of a widget record.
- field name field (in)
- The name of a field in records of type type.
- 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 configure
widget command). If non-NULL, then information is returned only for this
option. If NULL, then information is returned for all available
options.
- Display *display (in)
- Display containing widget whose record is being freed;
needed in order to free up resources.
DESCRIPTION¶
Note:
Tk_ConfigureWidget should be replaced with the new
Tcl_Obj
based API
Tk_SetOptions. The old interface is retained for backward
compatibility.
Tk_ConfigureWidget 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
configure command is
invoked for a widget. Although intended primarily for widgets,
Tk_ConfigureWidget can be used in other situations where
argc-argv 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.
Tk_ConfigureWidget processes a table specifying the configuration options
that are supported (
specs) and a collection of command-line arguments
(
argc and
argv) to fill in fields of a record (
widgRec).
It uses the option database and defaults specified in
specs to fill in
fields of
widgRec that are not specified in
argv.
Tk_ConfigureWidget normally returns the value
TCL_OK; in this
case it does not modify
interp. If an error occurs then
TCL_ERROR is returned and
Tk_ConfigureWidget will leave an error
message in
interp->result in the standard Tcl fashion. In the event
of an error return, some of the fields of
widgRec 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
Tk_FreeOptions can be called for cleanup.
The
specs array specifies the kinds of configuration options expected by
the widget. Each of its entries specifies one configuration option and has the
following structure:
typedef struct {
int type;
char * argvName;
char * dbName;
char * dbClass;
char * defValue;
int offset;
int specFlags;
Tk_CustomOption * customPtr;
} Tk_ConfigSpec;
The
type 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
type field indicates how to use the value of the
option (more on this below). The
argvName field is a string such as
“-font” or “-bg”, which is compared with the values in
argv (if
argvName is NULL it means this is a grouped entry; see
GROUPED ENTRIES below). The
dbName and
dbClass fields are
used to look up a value for this option in the option database. The
defValue field specifies a default value for this configuration option
if no value is specified in either
argv or the option database.
Offset indicates where in
widgRec to store information about
this option, and
specFlags contains additional information to control
the processing of this configuration option (see FLAGS below). The last field,
customPtr, is only used if
type is
TK_CONFIG_CUSTOM; see
CUSTOM OPTION TYPES below.
Tk_ConfigureWidget first processes
argv to see which (if any)
configuration options are specified there.
Argv must contain an even
number of fields; the first of each pair of fields must match the
argvName of some entry in
specs (unique abbreviations are
acceptable), and the second field of the pair contains the value for that
configuration option. If there are entries in
spec for which there were
no matching entries in
argv,
Tk_ConfigureWidget uses the
dbName and
dbClass fields of the
specs 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
defValue field of the
specs entry is used as the value for the
configuration option. If the
defValue is NULL, or if the
TK_CONFIG_DONT_SET_DEFAULT bit is set in
flags, then there is no
default value and this
specs entry will be ignored if no value is
specified in
argv or the option database.
Once a string value has been determined for a configuration option,
Tk_ConfigureWidget translates the string value into a more useful form,
such as a color if
type is
TK_CONFIG_COLOR or an integer if
type is
TK_CONFIG_INT. This value is then stored in the record
pointed to by
widgRec. This record is assumed to contain information
relevant to the manager of the widget; its exact type is unknown to
Tk_ConfigureWidget. The
offset field of each
specs entry
indicates where in
widgRec to store the information about this
configuration option. You should use the
Tk_Offset macro to generate
offset values (see below for a description of
Tk_Offset). The
location indicated by
widgRec and
offset will be referred to as
the “target” in the descriptions below.
The
type field of each entry in
specs determines what to do with
the string value of that configuration option. The legal values for
type, and the corresponding actions, are:
- TK_CONFIG_ACTIVE_CURSOR
- The value must be an ASCII string identifying a cursor in a
form suitable for passing to Tk_GetCursor. The value is converted
to a Tk_Cursor by calling Tk_GetCursor and the result is
stored in the target. In addition, the resulting cursor is made the active
cursor for tkwin by calling XDefineCursor. If
TK_CONFIG_NULL_OK is specified in specFlags then the value
may be an empty string, in which case the target and tkwin's active
cursor will be set to None. If the previous value of the target was
not None, then it is freed by passing it to
Tk_FreeCursor.
- TK_CONFIG_ANCHOR
- The value must be an ASCII string identifying an anchor
point in one of the ways accepted by Tk_GetAnchor. The string is
converted to a Tk_Anchor by calling Tk_GetAnchor and the
result is stored in the target.
- TK_CONFIG_BITMAP
- The value must be an ASCII string identifying a bitmap in a
form suitable for passing to Tk_GetBitmap. The value is converted
to a Pixmap by calling Tk_GetBitmap and the result is stored
in the target. If TK_CONFIG_NULL_OK is specified in
specFlags then the value may be an empty string, in which case the
target is set to None. If the previous value of the target was not
None, then it is freed by passing it to Tk_FreeBitmap.
- TK_CONFIG_BOOLEAN
- 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.
- TK_CONFIG_BORDER
- The value must be an ASCII string identifying a border
color in a form suitable for passing to Tk_Get3DBorder. The value
is converted to a ( Tk_3DBorder *) by calling Tk_Get3DBorder
and the result is stored in the target. If TK_CONFIG_NULL_OK is
specified in specFlags 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 was not NULL, then it is freed by passing it to
Tk_Free3DBorder.
- TK_CONFIG_CAP_STYLE
- The value must be an ASCII string identifying a cap style
in one of the ways accepted by Tk_GetCapStyle. The string is
converted to an integer value corresponding to the cap style by calling
Tk_GetCapStyle and the result is stored in the target.
- TK_CONFIG_COLOR
- The value must be an ASCII string identifying a color in a
form suitable for passing to Tk_GetColor. The value is converted to
an ( XColor *) by calling Tk_GetColor and the result is
stored in the target. If TK_CONFIG_NULL_OK is specified in
specFlags then the value may be an empty string, in which case the
target will be set to None. If the previous value of the target was
not NULL, then it is freed by passing it to Tk_FreeColor.
- TK_CONFIG_CURSOR
- This option is identical to TK_CONFIG_ACTIVE_CURSOR
except that the new cursor is not made the active one for
tkwin.
- TK_CONFIG_CUSTOM
- This option allows applications to define new option types.
The customPtr field of the entry points to a structure defining the
new option type. See the section CUSTOM OPTION TYPES below for
details.
- TK_CONFIG_DOUBLE
- The value must be an ASCII floating-point number in the
format accepted by strtol. The string is converted to a
double value, and the value is stored in the target.
- TK_CONFIG_END
- Marks the end of the table. The last entry in specs
must have this type; all of its other fields are ignored and it will never
match any arguments.
- TK_CONFIG_FONT
- The value must be an ASCII string identifying a font in a
form suitable for passing to Tk_GetFont. The value is converted to
a Tk_Font by calling Tk_GetFont and the result is stored in
the target. If TK_CONFIG_NULL_OK is specified in specFlags
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 was not NULL, then it is
freed by passing it to Tk_FreeFont.
- TK_CONFIG_INT
- The value must be an ASCII integer string in the format
accepted by strtol (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.
- TK_CONFIG_JOIN_STYLE
- The value must be an ASCII string identifying a join style
in one of the ways accepted by Tk_GetJoinStyle. The string is
converted to an integer value corresponding to the join style by calling
Tk_GetJoinStyle and the result is stored in the target.
- TK_CONFIG_JUSTIFY
- The value must be an ASCII string identifying a
justification method in one of the ways accepted by Tk_GetJustify.
The string is converted to a Tk_Justify by calling
Tk_GetJustify and the result is stored in the target.
- TK_CONFIG_MM
- The value must specify a screen distance in one of the
forms acceptable to Tk_GetScreenMM. The string is converted to
double-precision floating-point distance in millimeters and the value is
stored in the target.
- TK_CONFIG_PIXELS
- The value must specify screen units in one of the forms
acceptable to Tk_GetPixels. The string is converted to an integer
distance in pixels and the value is stored in the target.
- TK_CONFIG_RELIEF
- The value must be an ASCII string identifying a relief in a
form suitable for passing to Tk_GetRelief. The value is converted
to an integer relief value by calling Tk_GetRelief and the result
is stored in the target.
- TK_CONFIG_STRING
- A copy of the value is made by allocating memory space with
Tcl_Alloc 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 specFlags 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 was not NULL, then it is freed by passing
it to Tcl_Free.
- TK_CONFIG_SYNONYM
- This type value identifies special entries in
specs that are synonyms for other entries. If an argv value
matches the argvName of a TK_CONFIG_SYNONYM entry, the entry
is not used directly. Instead, Tk_ConfigureWidget searches
specs for another entry whose argvName is the same as the
dbName field in the TK_CONFIG_SYNONYM entry; this new entry
is used just as if its argvName had matched the argv value.
The synonym mechanism allows multiple argv values to be used for a
single configuration option, such as “-background” and
“-bg”.
- TK_CONFIG_UID
- The value is translated to a Tk_Uid (by passing it
to Tk_GetUid). The resulting value is stored in the target. If
TK_CONFIG_NULL_OK is specified in specFlags and the value is
an empty string then the target will be set to NULL.
- TK_CONFIG_WINDOW
- The value must be a window path name. It is translated to a
Tk_Window token and the token is stored in the target.
GROUPED ENTRIES¶
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
specs are to be treated as a group. The
first entry is used to determine a value (using its
argvName,
dbName,
dbClass, and
defValue fields). The value will be
processed several times (one for each entry in the group), generating multiple
different resources and modifying multiple targets within
widgRec. Each
of the entries after the first must have a NULL value in its
argvName
field; this indicates that the entry is to be grouped with the entry that
precedes it. Only the
type and
offset fields are used from these
follow-on entries.
FLAGS¶
The
flags argument passed to
Tk_ConfigureWidget is used in
conjunction with the
specFlags fields in the entries of
specs to
provide additional control over the processing of configuration options. These
values are used in three different ways as described below.
First, if the
flags argument to
Tk_ConfigureWidget has the
TK_CONFIG_ARGV_ONLY bit set (i.e.,
flags |
TK_CONFIG_ARGV_ONLY != 0), then the option database and
defValue
fields are not used. In this case, if an entry in
specs does not match
a field in
argv then nothing happens: the corresponding target is not
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
configure widget command is being processed.
Second, the
specFlags field of an entry in
specs may be used to
control the processing of that entry. Each
specFlags field may consists
of an OR-ed combination of the following values:
- TK_CONFIG_COLOR_ONLY
- If this bit is set then the entry will only be considered
if the display for tkwin has more than one bit plane. If the
display is monochromatic then this specs entry will be
ignored.
- TK_CONFIG_MONO_ONLY
- If this bit is set then the entry will only be considered
if the display for tkwin has exactly one bit plane. If the display
is not monochromatic then this specs entry will be ignored.
- TK_CONFIG_NULL_OK
- 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 None, 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 None so that a
window simply inherits its parent's cursor. If this bit is not set then
empty strings are processed as strings, which generally results in an
error.
- TK_CONFIG_DONT_SET_DEFAULT
- If this bit is one, it means that the defValue field
of the entry should only be used for returning the default value in
Tk_ConfigureInfo. In calls to Tk_ConfigureWidget 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 Tk_ConfigureWidget.
- TK_CONFIG_OPTION_SPECIFIED
- This bit is deprecated. It used to be set and cleared by
Tk_ConfigureWidget so that callers could detect what entries were
specified in argv, but it was removed because it was inherently
thread-unsafe. Code that wishes to detect what options were specified
should use Tk_SetOptions instead.
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
specs that are
identical except for their
defValue and
specFlags fields. One
entry should have the value
TK_CONFIG_MONO_ONLY in its
specFlags
and the default value for monochrome displays in its
defValue; the
other entry should have the value
TK_CONFIG_COLOR_ONLY in its
specFlags and the appropriate
defValue for color displays.
Third, it is possible to use
flags and
specFlags 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
specs 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
specFlags values or in
flags. In order for a particular entry in
specs to be used, its
high-order bits must match exactly the high-order bits of the
flags
value passed to
Tk_ConfigureWidget. If a
specs table is being
used for N different widget types, then N of the high-order bits will be used.
Each
specs entry will have one of more of those bits set in its
specFlags field to indicate the widget types for which this entry is
valid. When calling
Tk_ConfigureWidget,
flags 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.
TK_OFFSET¶
The
Tk_Offset macro is provided as a safe way of generating the
offset 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.
The
Tk_ConfigureInfo procedure may be used to obtain information about
one or all of the options for a given widget. Given a token for a window (
tkwin), a table describing the configuration options for a class of
widgets (
specs), a pointer to a widget record containing the current
information for a widget (
widgRec), and a NULL
argvName
argument,
Tk_ConfigureInfo generates a string describing all of the
configuration options for the window. The string is placed in
interp->result. Under normal circumstances it returns
TCL_OK;
if an error occurs then it returns
TCL_ERROR and
interp->result contains an error message.
If
argvName is NULL, then the value left in
interp->result by
Tk_ConfigureInfo consists of a list of one or more entries, each of
which describes one configuration option (i.e. one entry in
specs).
Each entry in the list will contain either two or five values. If the
corresponding entry in
specs has type
TK_CONFIG_SYNONYM, then
the list will contain two values: the
argvName for the entry and the
dbName (synonym name). Otherwise the list will contain five values:
argvName,
dbName,
dbClass,
defValue, and current
value. The current value is computed from the appropriate field of
widgRec by calling procedures like
Tk_NameOfColor.
If the
argvName argument to
Tk_ConfigureInfo is non-NULL, then it
indicates a single option, and information is returned only for that option.
The string placed in
interp->result 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
argvName had been NULL.
The
flags argument to
Tk_ConfigureInfo is used to restrict the
specs entries to consider, just as for
Tk_ConfigureWidget.
Tk_ConfigureValue takes arguments similar to
Tk_ConfigureInfo;
instead of returning a list of values, it just returns the current value of
the option given by
argvName (
argvName must not be NULL). The
value is returned in
interp->result and
TCL_OK is normally
returned as the procedure's result. If an error occurs in
Tk_ConfigureValue (e.g.,
argvName is not a valid option name),
TCL_ERROR is returned and an error message is left in
interp->result. This procedure is typically called to implement
cget widget commands.
TK_FREEOPTIONS¶
The
Tk_FreeOptions procedure may be invoked during widget cleanup to
release all of the resources associated with configuration options. It scans
through
specs 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 does not
refer to a resource (e.g. it contains a null pointer) then no resource is
freed for that entry. After freeing a resource,
Tk_FreeOptions sets the
corresponding field of the widget record to null.
CUSTOM OPTION TYPES¶
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:
typedef struct Tk_CustomOption {
Tk_OptionParseProc * parseProc;
Tk_OptionPrintProc * printProc;
ClientData clientData;
} Tk_CustomOption;
typedef int Tk_OptionParseProc(
ClientData clientData,
Tcl_Interp * interp,
Tk_Window tkwin,
char * value,
char * widgRec,
int offset);
typedef char *Tk_OptionPrintProc(
ClientData clientData,
Tk_Window tkwin,
char * widgRec,
int offset,
Tcl_FreeProc ** freeProcPtr);
The Tk_CustomOption structure contains three fields, which are pointers to the
two procedures and a
clientData value to be passed to those procedures
when they are invoked. The
clientData value typically points to a
structure containing information that is needed by the procedures when they
are parsing and printing options.
The
parseProc procedure is invoked by
Tk_ConfigureWidget to parse
a string and store the resulting value in the widget record. The
clientData argument is a copy of the
clientData field in the
Tk_CustomOption structure. The
interp argument points to a Tcl
interpreter used for error reporting.
Tkwin is a copy of the
tkwin argument to
Tk_ConfigureWidget. The
value argument
is a string describing the value for the option; it could have been specified
explicitly in the call to
Tk_ConfigureWidget or it could come from the
option database or a default.
Value will never be a null pointer but it
may point to an empty string.
RecordPtr is the same as the
widgRec argument to
Tk_ConfigureWidget; it points to the start
of the widget record to modify. The last argument,
offset, 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
interp->result.
The
printProc procedure is called by
Tk_ConfigureInfo to produce a
string value describing an existing option. Its
clientData,
tkwin,
widgRec, and
offset arguments all have the same
meaning as for Tk_OptionParseProc procedures. The
printProc procedure
should examine the option whose value is stored at
offset in
widgRec, 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
*freeProcPtr to the address of a procedure to
call to free the string's memory;
Tk_ConfigureInfo will call this
procedure when it is finished with the string. If the result string is stored
in static memory then
printProc need not do anything with the
freeProcPtr argument.
Once
parseProc and
printProc 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
type fields are
TK_CONFIG_CUSTOM and whose
customPtr fields point to the
Tk_CustomOption structure.
EXAMPLES¶
Although the explanation of
Tk_ConfigureWidget 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
specFlags mechanisms.
SEE ALSO¶
Tk_SetOptions(3tk)
KEYWORDS¶
anchor, bitmap, boolean, border, cap style, color, configuration options,
cursor, custom, double, font, integer, join style, justify, millimeters,
pixels, relief, synonym, uid