Index of Section 3 Manual Pages
| Interix / SUA | SetOptions.3 | Interix / SUA |
Tk_SetOptions(3) Tk Library Procedures Tk_SetOptions(3)
_________________________________________________________________
NAME
Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOp-
tions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSave-
dOptions, Tk_GetOptionValue, Tk_GetOptionInfo,
Tk_FreeConfigOptions, Tk_Offset - process configuration
options
SYNOPSIS
#include
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 inter-
preter. Most
procedures use
this only for
returning
error mes-
sages; if it
is NULL then
no error mes-
sages 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 infor-
mation that
describes the
configuration
options that
are supported.
Used to build
a
Tk_OptionTable.
The informa-
tion 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-
ateOp-
tionTable.
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_GetOption-
Value.
Tk_Window tkwin (in) For options
such as
TK_OPTION_COLOR,
this argument
indicates the
window in
which the
option will be
used. If
optionTable
uses no win-
dow-dependent
options, then
a NULL value
may be sup-
plied for this
argument.
int objc (in) Number of val-
ues in objv.
Tcl_Obj *CONST objv[] (in) Command-line
arguments for
setting con-
figuring
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 pre-
viously filled
in by
Tk_SetOptions
with old val-
ues of modi-
fied options.
Tcl_Obj *namePtr (in) The value of
this object is
the name of a
particular
option. If
NULL is passed
to Tk_GetOp-
tionInfo then
information is
returned for
all options.
Must not be
NULL when
Tk_GetOption-
Value 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 proce-
dures handle all the details of parsing options and stor-
ing 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 ``wid-
get 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 template that describes the various
options supported by that class of widget; there is a sep-
arate template for each kind of widget. The template con-
tains 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 template must be augmented with additional informa-
tion 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_CreateOp-
tionTable is called the first time that a widget of a par-
ticular 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 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 configura-
tion 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 informa-
tion 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 com-
mand 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 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 con-
forms 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 mes-
sage 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 imple-
ments 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 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 exam-
ple, 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 vari-
able 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 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 of the new options, then it should pass the struc-
ture to Tk_RestoreSavedOptions, which will copy the old
values back into the widget record and free the new val-
ues. 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_Restore-
SavedOptions. If the savePtr argument to Tk_SetOptions is
NULL then Tk_SetOptions frees each old option value imme-
diately when it sets a new value for the option. In this
case, if an error occurs in the third option, the old val-
ues for the first two options cannot be restored.
Tk_GetOptionValue returns the current value of a configu-
ration option for a particular widget. The namePtr argu-
ment 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 sublist 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-ele-
ment 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 generat-
ing 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_Cre-
ateOptionTable via its templatePtr argument describes the
configuration options supported 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 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 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 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 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, 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 inher-
its 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 center. The internal form is a Tk_Anchor
value like the ones returned by Tk_GetAnchorFro-
mObj.
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 procedures
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_Alloc3DBorder-
FromObj. 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_AllocColorFro-
mObj. 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_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_AllocCursorFro-
mObj. This option type requires tkwin to be sup-
plied 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_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 internal 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 sev-
eral 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 supplied 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 giv-
ing a distance in pixels, like the values returned
by Tk_GetPixelsFromObj. Note: if the objOffset
field isn't used then information about the origi-
nal value of this option will be lost. See OBJOFF-
SET 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 dynamically
allocated copy of the value. This option type sup-
ports 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_GetIndexFro-
mObj. 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 syn-
onym 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 proce-
dures 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 immedi-
ately 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 sim-
ple number. For example, after the command .b configure
-borderwidth 2m, the command .b configure -borderwidth
might return 7, which is the integer pixel value corre-
sponding to 2m. Unfortunately, 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 immedi-
ately 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, you can
use TK_OPTION_STRING as the type in the Tk_OptionSpec
structure and set the objOffset field but not the inter-
nalOffset field. Then, after calling Tk_SetOptions, con-
vert the object to internal form yourself.
CUSTOM OPTION TYPES
Applications can extend the built-in configuration types
with additional configuration types by writing procedures
to parse, print, free, and restore saved copies of the
type and creating a structure pointing to those proce-
dures:
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 pro-
cedures; and a clientData value to be passed to those pro-
cedures when they are invoked. The clientData value typi-
cally points to a structure containing information that is
needed by the procedures when they are parsing and print-
ing options. RestoreProc and freeProc may be NULL, indi-
cating that no function should be called for those opera-
tions.
The setProc procedure is invoked by Tk_SetOptions to con-
vert a Tcl_Obj into an internal representation 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_SetOp-
tions
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
referenced 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_Save-
dOptions structure for the internal repre-
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_RestoreSave-
dOptions.
flags A copy of the flags field in the Tk_Option-
Spec 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 representation of
the internal representation of an option. The clientData
argument is a copy of the clientData field in the Tk_Obj-
CustomOption 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 location
where the internal representation of the option value is
stored. GetProc must return a pointer to a Tcl_Obj repre-
senting the value of the option.
The restoreProc procedure is invoked by Tk_RestoreSavedOp-
tions to restore a previously saved internal representa-
tion 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 allocated for the
internal representation of a custom option. The client-
Data 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 inter-
nal 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)