SetOptions
Tk_SetOptions(3) Tk Library Procedures Tk_SetOptions(3)
______________________________________________________________________________
NAME
Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOp-
tions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue,
Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset - process configura-
tion options
SYNOPSIS
#include <tk.h>
Tk_OptionTable
Tk_CreateOptionTable(interp, templatePtr)
Tk_DeleteOptionTable(optionTable)
int
Tk_InitOptions(interp, recordPtr, optionTable, tkwin)
int
Tk_SetOptions(interp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr)
Tk_FreeSavedOptions(savedPtr)
Tk_RestoreSavedOptions(savedPtr)
Tcl_Obj *
Tk_GetOptionValue(interp, recordPtr, optionTable, namePtr, tkwin)
Tcl_Obj *
Tk_GetOptionInfo(interp, recordPtr, optionTable, namePtr, tkwin)
Tk_FreeConfigOptions(recordPtr, optionTable, tkwin)
int
Tk_Offset(type, field)
ARGUMENTS
Tcl_Interp *interp (in) A Tcl interpreter. Most
procedures use this only
for returning error mes-
sages; if it is NULL then
no error messages are
returned. For Tk_CreateOp-
tionTable the value cannot
be NULL; it gives the
interpreter in which the
option table will be used.
Tk_OptionSpec *templatePtr (in) Points to an array of
static information that
describes the configuration
options that are supported.
Used to build a
Tk_OptionTable. The infor-
mation pointed to by this
argument must exist for the
lifetime of the
Tk_OptionTable.
Tk_OptionTable optionTable (in) Token for an option table.
Must have been returned by
a previous call to Tk_Cre-
ateOptionTable.
char *recordPtr (in/out) Points to structure in
which values of configura-
tion options are stored;
fields of this record are
modified by procedures such
as Tk_SetOptions and read
by procedures such as
Tk_GetOptionValue.
Tk_Window tkwin (in) For options such as
TK_OPTION_COLOR, this argu-
ment indicates the window
in which the option will be
used. If optionTable uses
no window-dependent
options, then a NULL value
may be supplied for this
argument.
int objc (in) Number of values in objv.
Tcl_Obj *CONST objv[] (in) Command-line arguments for
setting configuring
options.
Tk_SavedOptions *savePtr (out) If not NULL, the structure
pointed to by this argument
is filled in with the old
values of any options that
were modified and old val-
ues are restored automati-
cally if an error occurs in
Tk_SetOptions.
int *maskPtr (out) If not NULL, the word
pointed to by maskPtr is
filled in with the bit-wise
OR of the typeMask fields
for the options that were
modified.
Tk_SavedOptions *savedPtr (in/out) Points to a structure pre-
viously filled in by
Tk_SetOptions with old val-
ues of modified options.
Tcl_Obj *namePtr (in) The value of this object is
the name of a particular
option. If NULL is passed
to Tk_GetOptionInfo then
information is returned for
all options. Must not be
NULL when Tk_GetOptionValue
is called.
type name type (in) The name of the type of a
record.
field name field (in) The name of a field in
records of type type.
_________________________________________________________________
DESCRIPTION
These procedures handle most of the details of parsing configuration
options such as those for Tk widgets. Given a description of what
options are supported, these procedures handle all the details of pars-
ing options and storing their values into a C structure associated with
the widget or object. The procedures were designed primarily for wid-
gets in Tk, but they can also be used for other kinds of objects that
have configuration options. In the rest of this manual page ``widget''
will be used to refer to the object whose options are being managed; in
practice the object may not actually be a widget. The term ``widget
record'' is used to refer to the C-level structure in which information
about a particular widget or object is stored.
Note: the easiest way to learn how to use these procedures is to look
at a working example. In Tk, the simplest example is the code that
implements the button family of widgets, which is an tkButton.c. Other
examples are in tkSquare.c and tkMenu.c.
In order to use these procedures, the code that implements the widget
must contain a static array of Tk_OptionSpec structures. This is a tem-
plate that describes the various options supported by that class of
widget; there is a separate template for each kind of widget. The tem-
plate contains information such as the name of each option, its type,
its default value, and where the value of the option is stored in the
widget record. See TEMPLATES below for more detail.
In order to process configuration options efficiently, the static tem-
plate must be augmented with additional information that is available
only at runtime. The procedure Tk_CreateOptionTable creates this
dynamic information from the template and returns a Tk_OptionTable
token that describes both the static and dynamic information. All of
the other procedures, such as Tk_SetOptions, take a Tk_OptionTable
token as argument. Typically, Tk_CreateOptionTable is called the first
time that a widget of a particular class is created and the resulting
Tk_OptionTable is used in the future for all widgets of that class. A
Tk_OptionTable may be used only in a single interpreter, given by the
interp argument to Tk_CreateOptionTable. When an option table is no
longer needed Tk_DeleteOptionTable should be called to free all of its
resources. All of the option tables for a Tcl interpreter are freed
automatically if the interpreter is deleted.
Tk_InitOptions is invoked when a new widget is created to set the
default values for all of the widget's configuration options. Tk_Ini-
tOptions is passed a token for an option table (optionTable) and a
pointer to a widget record (recordPtr), which is the C structure that
holds information about this widget. Tk_InitOptions uses the informa-
tion in the option table to choose an appropriate default for each
option, then it stores the default value directly into the widget
record, overwriting any information that was already present in the
widget record. Tk_InitOptions normally returns TCL_OK. If an error
occurred while setting the default values (e.g., because a default
value was erroneous) then TCL_ERROR is returned and an error message is
left in interp's result if interp isn't NULL.
Tk_SetOptions is invoked to modify configuration options based on
information specified in a Tcl command. The command might be one that
creates a new widget, or a command that modifies options on an existing
widget. The objc and objv arguments describe the values of the argu-
ments from the Tcl command. Objv must contain an even number of
objects: the first object of each pair gives the name of an option and
the second object gives the new value for that option. Tk_SetOptions
looks up each name in optionTable, checks that the new value of the
option conforms to the type in optionTable, and stores the value of the
option into the widget record given by recordPtr. Tk_SetOptions nor-
mally returns TCL_OK. If an error occurred (such as an unknown option
name or an illegal option value) then TCL_ERROR is returned and an
error message is left in interp's result if interp isn't NULL.
Tk_SetOptions has two additional features. First, if the maskPtr argu-
ment isn't NULL then it points to an integer value that is filled in
with information about the options that were modified. For each option
in the template passed to Tk_CreateOptionTable there is a typeMask
field. The bits of this field are defined by the code that implements
the widget; for example, each bit might correspond to a particular con-
figuration option. Alternatively, bits might be used functionally.
For example, one bit might be used for redisplay: all options that
affect the widget's display, such that changing the option requires the
widget to be redisplayed, might have that bit set. Another bit might
indicate that the geometry of the widget must be recomputed, and so on.
Tk_SetOptions OR's together the typeMask fields from all the options
that were modified and returns this value at *maskPtr; the caller can
then use this information to optimize itself so that, for example, it
doesn't redisplay the widget if the modified options don't affect the
widget's appearance.
The second additional feature of Tk_SetOptions has to do with error
recovery. If an error occurs while processing configuration options,
this feature makes it possible to restore all the configuration options
to their previous values. Errors can occur either while processing
options in Tk_SetOptions or later in the caller. In many cases the
caller does additional processing after Tk_SetOptions returns; for
example, it might use an option value to set a trace on a variable and
may detect an error if the variable is an array instead of a scalar.
Error recovery is enabled by passing in a non-NULL value for the
savePtr argument to Tk_SetOptions; this should be a pointer to an
uninitialized Tk_SavedOptions structure on the caller's stack.
Tk_SetOptions overwrites the structure pointed to by savePtr with
information about the old values of any options modified by the proce-
dure. If Tk_SetOptions returns successfully, the caller uses the
structure in one of two ways. If the caller completes its processing
of the new options without any errors, then it must pass the structure
to Tk_FreeSavedOptions so that the old values can be freed. If the
caller detects an error in its processing of the new options, then it
should pass the structure to Tk_RestoreSavedOptions, which will copy
the old values back into the widget record and free the new values. If
Tk_SetOptions detects an error then it automatically restores any
options that had already been modified and leaves *savePtr in an empty
state: the caller need not call either Tk_FreeSavedOptions or
Tk_RestoreSavedOptions. If the savePtr argument to Tk_SetOptions is
NULL then Tk_SetOptions frees each old option value immediately when it
sets a new value for the option. In this case, if an error occurs in
the third option, the old values for the first two options cannot be
restored.
Tk_GetOptionValue returns the current value of a configuration option
for a particular widget. The namePtr argument contains the name of an
option; Tk_GetOptionValue uses optionTable to lookup the option and
extract its value from the widget record pointed to by recordPtr, then
it returns an object containing that value. If an error occurs (e.g.,
because namePtr contains an unknown option name) then NULL is returned
and an error message is left in interp's result unless interp is NULL.
Tk_GetOptionInfo returns information about configuration options in a
form suitable for configure widget commands. If the namePtr argument
is not NULL, it points to an object that gives the name of a configura-
tion option; Tk_GetOptionInfo returns an object containing a list with
five elements, which are the name of the option, the name and class
used for the option in the option database, the default value for the
option, and the current value for the option. If the namePtr argument
is NULL, then Tk_GetOptionInfo returns information about all options in
the form of a list of lists; each sublist describes one option. Syn-
onym options are handled differently depending on whether namePtr is
NULL: if namePtr is NULL then the sublist for each synonym option has
only two elements, which are the name of the option and the name of the
other option that it refers to; if namePtr is non-NULL and names a syn-
onym option then the object returned is the five-element list for the
other option that the synonym refers to. If an error occurs (e.g.,
because namePtr contains an unknown option name) then NULL is returned
and an error message is left in interp's result unless interp is NULL.
Tk_FreeConfigOptions must be invoked when a widget is deleted. It
frees all of the resources associated with any of the configuration
options defined in recordPtr by optionTable.
The Tk_Offset macro is provided as a safe way of generating the objOff-
set and internalOffset values for entries in Tk_OptionSpec structures.
It takes two arguments: the name of a type of record, and the name of a
field in that record. It returns the byte offset of the named field in
records of the given type.
TEMPLATES
The array of Tk_OptionSpec structures passed to Tk_CreateOptionTable
via its templatePtr argument describes the configuration options sup-
ported by a particular class of widgets. Each structure specifies one
configuration option and has the following fields:
typedef struct {
Tk_OptionType type;
char *optionName;
char *dbName;
char *dbClass;
char *defValue;
int objOffset;
int internalOffset;
int flags;
ClientData clientData;
int typeMask;
} Tk_OptionSpec;
The type field indicates what kind of configuration option this is
(e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for an inte-
ger value). Type determines how the value of the option is parsed
(more on this below). The optionName field is a string such as -font
or -bg; it is the name used for the option in Tcl commands and passed
to procedures via the objc or namePtr arguments. The dbName and
dbClass fields are used by Tk_InitOptions to look up a default value
for this option in the option database; if dbName is NULL then the
option database is not used by Tk_InitOptions for this option. The
defValue field specifies a default value for this configuration option
if no value is specified in the option database. The objOffset and
internalOffset fields indicate where to store the value of this option
in widget records (more on this below); values for the objOffset and
internalOffset fields should always be generated with the Tk_Offset
macro. The flags field contains additional information to control the
processing of this configuration option (see below for details).
ClientData provides additional type-specific data needed by certain
types. For instance, for TK_OPTION_COLOR types, clientData is a string
giving the default value to use on monochrome displays. See the
descriptions of the different types below for details. The last field,
typeMask, is used by Tk_SetOptions to return information about which
options were modified; see the description of Tk_SetOptions above for
details.
When Tk_InitOptions and Tk_SetOptions store the value of an option into
the widget record, they can do it in either of two ways. If the
objOffset field of the Tk_OptionSpec is greater than or equal to zero,
then the value of the option is stored as a (Tcl_Obj *) at the location
in the widget record given by objOffset. If the internalOffset field
of the Tk_OptionSpec is greater than or equal to zero, then the value
of the option is stored in a type-specific internal form at the loca-
tion in the widget record given by internalOffset. For example, if the
option's type is TK_OPTION_INT then the internal form is an integer.
If the objOffset or internalOffset field is negative then the value is
not stored in that form. At least one of the offsets must be greater
than or equal to zero.
The flags field consists of one or more bits ORed together. At present
only a single flag is supported: TK_OPTION_NULL_OK. If this bit is set
for an option then an empty string will be accepted as the value for
the option and the resulting internal form will be a NULL pointer or
None, depending on the type of the option. If the flag is not set then
empty strings will result in errors. TK_OPTION_NULL_OK is typically
used to allow a feature to be turned off entirely, e.g. set a cursor
value to None so that a window simply inherits its parent's cursor.
Not all option types support the TK_OPTION_NULL_OK flag; for those that
do, there is an explicit indication of that fact in the descriptions
below.
The type field of each Tk_OptionSpec structure determines how to parse
the value of that configuration option. The legal value for type, and
the corresponding actions, are described below. If the type requires a
tkwin value to be passed into procedures like Tk_SetOptions, or if it
uses the clientData field of the Tk_OptionSpec, then it is indicated
explicitly; if not mentioned, the type requires neither tkwin nor
clientData.
TK_OPTION_ANCHOR
The value must be a standard anchor position such as ne or cen-
ter. The internal form is a Tk_Anchor value like the ones
returned by Tk_GetAnchorFromObj.
TK_OPTION_BITMAP
The value must be a standard Tk bitmap name. The internal form
is a Pixmap token like the ones returned by Tk_AllocBitmapFro-
mObj. This option type requires tkwin to be supplied to proce-
dures such as Tk_SetOptions, and it supports the
TK_OPTION_NULL_OK flag.
TK_OPTION_BOOLEAN
The value must be a standard boolean value such as true or no.
The internal form is an integer with value 0 or 1.
TK_OPTION_BORDER
The value must be a standard color name such as red or #ff8080.
The internal form is a Tk_3DBorder token like the ones returned
by Tk_Alloc3DBorderFromObj. This option type requires tkwin to
be supplied to procedures such as Tk_SetOptions, and it supports
the TK_OPTION_NULL_OK flag.
TK_OPTION_COLOR
The value must be a standard color name such as red or #ff8080.
The internal form is an (XColor *) token like the ones returned
by Tk_AllocColorFromObj. This option type requires tkwin to be
supplied to procedures such as Tk_SetOptions, and it supports
the TK_OPTION_NULL_OK flag.
TK_OPTION_CURSOR
The value must be a standard cursor name such as cross or @foo.
The internal form is a Tk_Cursor token like the ones returned by
Tk_AllocCursorFromObj. This option type requires tkwin to be
supplied to procedures such as Tk_SetOptions, and when the
option is set the cursor for the window is changed by calling
XDefineCursor. This option type also supports the
TK_OPTION_NULL_OK flag.
TK_OPTION_DOUBLE
The string value must be a floating-point number in the format
accepted by strtol. The internal form is a C double value.
TK_OPTION_END
Marks the end of the template. There must be a Tk_OptionSpec
structure with type TK_OPTION_END at the end of each template.
If the clientData field of this structure isn't NULL, then it
points to an additional array of Tk_OptionSpec's, which is
itself terminated by another TK_OPTION_END entry. Templates may
be chained arbitrarily deeply. This feature allows common
options to be shared by several widget classes.
TK_OPTION_FONT
The value must be a standard font name such as Times 16. The
internal form is a Tk_Font handle like the ones returned by
Tk_AllocFontFromObj. This option type requires tkwin to be sup-
plied to procedures such as Tk_SetOptions, and it supports the
TK_OPTION_NULL_OK flag.
TK_OPTION_INT
The string value must be an integer in the format accepted by
strtol (e.g. 0 and 0x prefixes may be used to specify octal or
hexadecimal numbers, respectively). The internal form is a C
int value.
TK_OPTION_JUSTIFY
The value must be a standard justification value such as left.
The internal form is a Tk_Justify like the values returned by
Tk_GetJustifyFromObj.
TK_OPTION_PIXELS
The value must specify a screen distance such as 2i or 6.4. The
internal form is an integer value giving a distance in pixels,
like the values returned by Tk_GetPixelsFromObj. Note: if the
objOffset field isn't used then information about the original
value of this option will be lost. See OBJOFFSET VS. INTER-
NALOFFSET below for details.
TK_OPTION_RELIEF
The value must be standard relief such as raised. The internal
form is an integer relief value such as TK_RELIEF_RAISED.
TK_OPTION_STRING
The value may be any string. The internal form is a (char *)
pointer that points to a dynamically allocated copy of the
value. This option type supports the TK_OPTION_NULL_OK flag.
TK_OPTION_STRING_TABLE
For this type, clientData is a pointer to an array of strings
suitable for passing to Tcl_GetIndexFromObj. The value must be
one of the strings in the table, or a unique abbreviation of one
of the strings. The internal form is an integer giving the
index into the table of the matching string, like the return
value from Tcl_GetStringFromObj.
TK_OPTION_SYNONYM
This type is used to provide alternative names for an option
(for example, -bg is often used as a synonym for -background).
The clientData field is a (char *) pointer that gives the name
of another option in the same table. Whenever the synonym
option is used, the information from the other option will be
used instead.
TK_OPTION_WINDOW
The value must be a window path name. The internal form is a
Tk_Window token for the window. This option type requires tkwin
to be supplied to procedures such as Tk_SetOptions (in order to
identify the application), and it supports the TK_OPTION_NULL_OK
flag.
STORAGE MANAGEMENT ISSUES
If a field of a widget record has its offset stored in the objOffset or
internalOffset field of a Tk_OptionSpec structure then the procedures
described here will handle all of the storage allocation and resource
management issues associated with the field. When the value of an
option is changed, Tk_SetOptions (or Tk_FreeSavedOptions will automati-
cally free any resources associated with the old value, such as
Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for
TK_OPTION_STRING options. For an option stored as an object using the
objOffset field of a Tk_OptionSpec, the widget record shares the object
pointed to by the objv value from the call to Tk_SetOptions. The ref-
erence count for this object is incremented when a pointer to it is
stored in the widget record and decremented when the option is modi-
fied. When the widget is deleted Tk_FreeConfigOptions should be
invoked; it will free the resources associated with all options and
decrement reference counts for any objects.
However, the widget code is responsible for storing NULL or None in all
pointer and token fields before invoking Tk_InitOptions. This is
needed to allow proper cleanup in the rare case where an error occurs
in Tk_InitOptions.
OBJOFFSET VS. INTERNALOFFSET
In most cases it is simplest to use the internalOffset field of a
Tk_OptionSpec structure and not the objOffset field. This makes the
internal form of the value immediately available to the widget code so
the value doesn't have to be extracted from an object each time it is
used. However, there are two cases where the objOffset field is use-
ful. The first case is for TK_OPTION_PIXELS options. In this case,
the internal form is an integer pixel value that is valid only for a
particular screen. If the value of the option is retrieved, it will be
returned as a simple number. For example, after the command .b config-
ure -borderwidth 2m, the command .b configure -borderwidth might return
7, which is the integer pixel value corresponding to 2m. Unfortu-
nately, this loses the original screen-independent value. Thus for
TK_OPTION_PIXELS options it is better to use the objOffset field. In
this case the original value of the option is retained in the object
and can be returned when the option is retrieved. In most cases it is
convenient to use the internalOffset field field as well, so that the
integer value is immediately available for use in the widget code
(alternatively, Tk_GetPixelsFromObj can be used to extract the integer
value from the object whenever it is needed). Note: the problem of
losing information on retrievals exists only for TK_OPTION_PIXELS
options.
The second reason to use the objOffset field is in order to implement
new types of options not supported by these procedures. To implement a
new type of option, use TK_OPTION_STRING as the type in the Tk_Option-
Spec structure and set the objOffset field but not the internalOffset
field. Then, after calling Tk_SetOptions, convert the object to inter-
nal form yourself.
KEYWORDS
anchor, bitmap, boolean, border, color, configuration option, cursor,
double, font, integer, justify, pixels, relief, screen distance, syn-
onym
Tk 8.1 Tk_SetOptions(3)
