Tk_SetOptions(3) Tk Library Procedures Tk_SetOptions(3)
____________________________________________________________________________________________________________
NAME
Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions,
Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset -process Tk_Offsetprocess
process configuration 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 messages; if it is NULL then no error
messages are returned. For Tk_CreateOptionTable 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 information 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_CreateOptionTable.
char *recordPtr (in/out) Points to structure in which values of configuration
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 argument indi-cates indicates
cates 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 values are restored automatically 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 previously filled in by Tk_SetOp-tions Tk_SetOptions
tions with old values 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 parsing options and storing their values into a C structure associated with the widget or object.
The procedures were designed primarily for widgets 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 tkBut-ton.c. tkButton.c.
ton.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 template that describes the various options supported by that
class of widget; there is a separate template for each kind of widget. The template contains infor-mation information
mation 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 template 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_DeleteOp-tionTable Tk_DeleteOptionTable
tionTable should be called to free all of its resources. All of the option tables for a Tcl inter-preter interpreter
preter 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 wid-get's widget's
get's configuration options. Tk_InitOptions 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 information 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 infor-mation information
mation 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 com-mand. command.
mand. 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 arguments from the Tcl com-mand. command.
mand. 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 normally
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 argument 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 configuration 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 indi-cate indicate
cate 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 configura-tion configuration
tion options to their previous values. Errors can occur either while processing options in Tk_SetOp-tions Tk_SetOptions
tions or later in the caller. In many cases the caller does additional processing after Tk_SetOp-tions Tk_SetOptions
tions 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 uninitial-ized uninitialized
ized 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 procedure. 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 pro-cessing processing
cessing 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 immedi-ately immediately
ately 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 configuration 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 sub-list sublist
list describes one option. Synonym 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 synonym 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 associ-ated associated
ated with any of the configuration options defined in recordPtr by optionTable.
The Tk_Offset macro is provided as a safe way of generating the objOffset 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 supported by a particular class of widgets. Each structure spec-ifies specifies
ifies 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 integer 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 inter-nalOffset internalOffset
nalOffset fields should always be generated with the Tk_Offset macro. The flags field contains addi-tional additional
tional 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 location 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 sup-ported: supported:
ported: 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, a zero value, 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 sup-port support
port 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 configura-tion configuration
tion 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 center. 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_AllocBitmapFromObj. This option type requires tkwin to be supplied to proce-dures procedures
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 inte-ger integer
ger 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 cur-sor cursor
sor for the window is changed by calling XDefineCursor. This option type also supports the
TK_OPTION_NULL_OK flag.
TK_OPTION_CUSTOM
This option allows applications to define new option types. The clientData field of the entry
points to a structure defining the new option type. See the section CUSTOM OPTION TYPES below
for details.
TK_OPTION_DOUBLE
The string value must be a floating-point number in the format accepted by strtol. The inter-nal internal
nal form is a C double value. This option type supports the TK_OPTION_NULL_OK flag; if a NULL
value is set, the internal representation is set to zero.
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 han-dle handle
dle like the ones returned by Tk_AllocFontFromObj. This option type requires tkwin to be sup-plied supplied
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_Jus-tify Tk_Justify
tify 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. INTERNALOFFSET below for details. This option type supports the
TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to zero.
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. This option type supports the TK_OPTION_NULL_OK flag; if the
empty string is specified as the value for the option, the integer relief value is set to
TK_RELIEF_NULL.
TK_OPTION_STRING
The value may be any string. The internal form is a (char *) pointer that points to a dynami-cally dynamically
cally 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 abbrevia-tion abbreviation
tion 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 automatically 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 reference count for this object is incremented when a pointer to it is stored in
the widget record and decremented when the option is modified. 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 useful. 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 configure -borderwidth 2m, the command .b configure -borderwidth might return 7, which
is the integer pixel value corresponding to 2m. Unfortunately, this loses the original screen-inde-pendent screen-independent
pendent 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_GetPixels-FromObj Tk_GetPixelsFromObj
FromObj 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 sup-ported supported
ported by these procedures. To implement a new type of option, you can use TK_OPTION_STRING as the
type in the Tk_OptionSpec structure and set the objOffset field but not the internalOffset field.
Then, after calling Tk_SetOptions, convert the object to internal form yourself.
CUSTOM OPTION TYPES
Applications can extend the built-in configuration types with additional configuration types by writ-ing writing
ing procedures to parse, print, free, and restore saved copies of the type and creating a structure
pointing to those procedures:
typedef struct Tk_ObjCustomOption {
char *name;
Tk_CustomOptionSetProc *setProc;
Tk_CustomOptionGetProc *getProc;
Tk_CustomOptionRestoreProc *restoreProc;
Tk_CustomOptionFreeProc *freeProc;
ClientData clientData;
} Tk_ObjCustomOption;
typedef int Tk_CustomOptionSetProc(
ClientData clientData,
Tcl_Interp *interp,
Tk_Window tkwin,
Tcl_Obj **valuePtr,
char *recordPtr,
int internalOffset,
char *saveInternalPtr,
int flags);
typedef Tcl_Obj *Tk_CustomOptionGetProc(
ClientData clientData,
Tk_Window tkwin,
char *recordPtr,
int internalOffset);
typedef void Tk_CustomOptionRestoreProc(
ClientData clientData,
Tk_Window tkwin,
char *internalPtr,
char *saveInternalPtr);
typedef void Tk_CustomOptionFreeProc(
ClientData clientData,
Tk_Window tkwin,
char *internalPtr);
The Tk_ObjCustomOption structure contains six fields: a name for the custom option type; pointers to
the four 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. RestoreProc and freeProc may be NULL, indi-cating indicating
cating that no function should be called for those operations.
The setProc procedure is invoked by Tk_SetOptions to convert a Tcl_Obj into an internal representa-tion representation
tion and store the resulting value in the widget record. The arguments are:
clientData
A copy of the clientData field in the Tk_ObjCustomOption structure.
interp A pointer to a Tcl interpreter, used for error reporting.
Tkwin A copy of the tkwin argument to Tk_SetOptions
valuePtr
A pointer to a reference to a Tcl_Obj describing the new value for the option; it could
have been specified explicitly in the call to Tk_SetOptions or it could come from the
option database or a default. If the objOffset for the option is non-negative (the
option value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj pointer ref-erenced referenced
erenced by valuePtr is the pointer that will be stored at the objOffset for the option.
SetProc may modify the value if necessary; for example, setProc may change the value to
NULL to support the TK_OPTION_NULL_OK flag.
recordPtr
A pointer to the start of the widget record to modify.
internalOffset
Offset in bytes from the start of the widget record to the location where the internal
representation of the option value is to be placed.
saveInternalPtr
A pointer to storage allocated in a Tk_SavedOptions structure for the internal repre-sentation representation
sentation of the original option value. Before setting the option to its new value,
setProc should set the value referenced by saveInternalPtr to the original value of the
option in order to support Tk_RestoreSavedOptions.
flags A copy of the flags field in the Tk_OptionSpec structure for the option
SetProc returns a standard Tcl result: TCL_OK to indicate successful processing, or TCL_ERROR to
indicate a failure of any kind. An error message may be left in the Tcl interpreter given by interp
in the case of an error.
The getProc procedure is invoked by Tk_GetOptionValue and Tk_GetOptionInfo to retrieve a Tcl_Obj rep-resentation representation
resentation of the internal representation of an option. The clientData argument is a copy of the
clientData field in the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argument to
Tk_GetOptionValue or Tk_GetOptionInfo. RecordPtr is a pointer to the beginning of the widget record
to query. InternalOffset is the offset in bytes from the beginning of the widget record to the loca-tion location
tion where the internal representation of the option value is stored. GetProc must return a pointer
to a Tcl_Obj representing the value of the option.
The restoreProc procedure is invoked by Tk_RestoreSavedOptions to restore a previously saved internal
representation of a custom option value. The clientData argument is a copy of the clientData field
in the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argument to Tk_GetOptionValue or
Tk_GetOptionInfo. InternalPtr is a pointer to the location where internal representation of the
option value is stored. SaveInternalPtr is a pointer to the saved value. RestoreProc must copy the
value from saveInternalPtr to internalPtr to restore the value. RestoreProc need not free any memory
associated with either internalPtr or saveInternalPtr; freeProc will be invoked to free that memory
if necessary. RestoreProc has no return value.
The freeProc procedure is invoked by Tk_SetOptions and Tk_FreeSavedOptions to free any storage allo-cated allocated
cated for the internal representation of a custom option. The clientData argument is a copy of the
clientData field in the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argument to
Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr is a pointer to the location where the internal
representation of the option value is stored. The freeProc must free any storage associated with the
option. FreeProc has no return value.
KEYWORDS
anchor, bitmap, boolean, border, color, configuration option, cursor, double, font, integer, justify,
pixels, relief, screen distance, synonym
Tk 8.1 Tk_SetOptions(3)
|