Provided by: tk8.5-doc_8.5.15-2ubuntu3_all 
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.
TK_CONFIGUREINFO
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
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