647 lines
32 KiB
Groff
647 lines
32 KiB
Groff
'\"
|
|
'\" Copyright (c) 1998 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
.so man.macros
|
|
.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tk.h>\fR
|
|
.sp
|
|
Tk_OptionTable
|
|
\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR
|
|
.sp
|
|
\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR
|
|
.sp
|
|
int
|
|
\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR
|
|
.sp
|
|
int
|
|
\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR
|
|
.sp
|
|
\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR
|
|
.sp
|
|
\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR
|
|
.sp
|
|
Tcl_Obj *
|
|
\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
|
|
.sp
|
|
Tcl_Obj *
|
|
\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
|
|
.sp
|
|
\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR
|
|
.sp
|
|
int
|
|
\fBTk_Offset(\fItype, field\fB)\fR
|
|
.SH ARGUMENTS
|
|
.AS Tk_SavedOptions "*const objv[]" in/out
|
|
.AP 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
|
|
\fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the
|
|
interpreter in which the option table will be used.
|
|
.AP "const 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.
|
|
.AP Tk_OptionTable optionTable in
|
|
Token for an option table. Must have been returned by a previous call
|
|
to \fBTk_CreateOptionTable\fR.
|
|
.AP 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 \fBTk_SetOptions\fR
|
|
and read by procedures such as \fBTk_GetOptionValue\fR.
|
|
.AP Tk_Window tkwin in
|
|
For options such as \fBTK_OPTION_COLOR\fR, this argument indicates
|
|
the window in which the option will be used. If \fIoptionTable\fR uses
|
|
no window-dependent options, then a NULL value may be supplied for
|
|
this argument.
|
|
.AP int objc in
|
|
Number of values in \fIobjv\fR.
|
|
.AP Tcl_Obj "*const objv[]" in
|
|
Command-line arguments for setting configuring options.
|
|
.AP 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 \fBTk_SetOptions\fR.
|
|
.AP int *maskPtr out
|
|
If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the
|
|
bit-wise OR of the \fItypeMask\fR fields for the options that
|
|
were modified.
|
|
.AP Tk_SavedOptions *savedPtr in/out
|
|
Points to a structure previously filled in by \fBTk_SetOptions\fR with
|
|
old values of modified options.
|
|
.AP Tcl_Obj *namePtr in
|
|
The value of this object is the name of a particular option. If NULL
|
|
is passed to \fBTk_GetOptionInfo\fR then information is returned for
|
|
all options. Must not be NULL when \fBTk_GetOptionValue\fR is called.
|
|
.AP "type name" type in
|
|
The name of the type of a record.
|
|
.AP "field name" field in
|
|
The name of a field in records of type \fItype\fR.
|
|
.BE
|
|
.SH DESCRIPTION
|
|
.PP
|
|
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
|
|
.QW 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
|
|
.QW "widget record"
|
|
is used to refer to the C-level structure in
|
|
which information about a particular widget or object is stored.
|
|
.PP
|
|
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 in \fBtkButton.c\fR.
|
|
Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR.
|
|
.PP
|
|
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 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.
|
|
.PP
|
|
In order to process configuration options efficiently, the static
|
|
template must be augmented with additional information that is available
|
|
only at runtime. The procedure \fBTk_CreateOptionTable\fR 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 \fBTk_SetOptions\fR, take a Tk_OptionTable
|
|
token as argument. Typically, \fBTk_CreateOptionTable\fR 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 \fIinterp\fR argument to \fBTk_CreateOptionTable\fR. When an
|
|
option table is no longer needed \fBTk_DeleteOptionTable\fR 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.
|
|
.PP
|
|
\fBTk_InitOptions\fR is invoked when a new widget is created to set
|
|
the default values for all of the widget's configuration options.
|
|
\fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR)
|
|
and a pointer to a widget record (\fIrecordPtr\fR), which is the C
|
|
structure that holds information about this widget. \fBTk_InitOptions\fR
|
|
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 information that
|
|
was already present in the widget record. \fBTk_InitOptions\fR normally
|
|
returns \fBTCL_OK\fR. If an error occurred while setting the default values
|
|
(e.g., because a default value was erroneous) then \fBTCL_ERROR\fR is returned
|
|
and an error message is left in \fIinterp\fR's result if \fIinterp\fR
|
|
is not NULL.
|
|
.PP
|
|
\fBTk_SetOptions\fR 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 \fIobjc\fR and \fIobjv\fR arguments describe the
|
|
values of the arguments from the Tcl command. \fIObjv\fR 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.
|
|
\fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that
|
|
the new value of the option conforms to the type in \fIoptionTable\fR,
|
|
and stores the value of the option into the widget record given by
|
|
\fIrecordPtr\fR. \fBTk_SetOptions\fR normally returns \fBTCL_OK\fR. If
|
|
an error occurred (such as an unknown option name or an illegal option
|
|
value) then \fBTCL_ERROR\fR is returned and an error message is left in
|
|
\fIinterp\fR's result if \fIinterp\fR is not NULL.
|
|
.PP
|
|
\fBTk_SetOptions\fR has two additional features. First, if the
|
|
\fImaskPtr\fR argument is not 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
|
|
\fBTk_CreateOptionTable\fR there is a \fItypeMask\fR 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 indicate that the geometry of the widget
|
|
must be recomputed, and so on. \fBTk_SetOptions\fR OR's together the
|
|
\fItypeMask\fR fields from all the options that were modified and returns
|
|
this value at *\fImaskPtr\fR; the caller can then use this information
|
|
to optimize itself so that, for example, it does not redisplay the widget
|
|
if the modified options do not affect the widget's appearance.
|
|
.PP
|
|
The second additional feature of \fBTk_SetOptions\fR 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
|
|
\fBTk_SetOptions\fR or later in the caller. In many cases the caller does
|
|
additional processing after \fBTk_SetOptions\fR 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 \fIsavePtr\fR argument
|
|
to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized
|
|
Tk_SavedOptions structure on the caller's stack. \fBTk_SetOptions\fR
|
|
overwrites the structure pointed to by \fIsavePtr\fR with information
|
|
about the old values of any options modified by the procedure.
|
|
If \fBTk_SetOptions\fR 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 \fBTk_FreeSavedOptions\fR 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 \fBTk_RestoreSavedOptions\fR,
|
|
which will copy the old values back into the widget record and free
|
|
the new values.
|
|
If \fBTk_SetOptions\fR detects an error then it automatically restores
|
|
any options that had already been modified and leaves *\fIsavePtr\fR in
|
|
an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or
|
|
\fBTk_RestoreSavedOptions\fR.
|
|
If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then
|
|
\fBTk_SetOptions\fR 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.
|
|
.PP
|
|
\fBTk_GetOptionValue\fR returns the current value of a configuration option
|
|
for a particular widget. The \fInamePtr\fR argument contains the name of
|
|
an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR
|
|
to lookup the option and extract its value from the widget record
|
|
pointed to by \fIrecordPtr\fR, then it returns an object containing
|
|
that value. If an error occurs (e.g., because \fInamePtr\fR contains an
|
|
unknown option name) then NULL is returned and an error message is left
|
|
in \fIinterp\fR's result unless \fIinterp\fR is NULL.
|
|
.PP
|
|
\fBTk_GetOptionInfo\fR returns information about configuration options in
|
|
a form suitable for \fBconfigure\fR widget commands. If the \fInamePtr\fR
|
|
argument is not NULL, it points to an object that gives the name of a
|
|
configuration option; \fBTk_GetOptionInfo\fR 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 \fInamePtr\fR
|
|
argument is NULL, then \fBTk_GetOptionInfo\fR 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
|
|
\fInamePtr\fR is NULL: if \fInamePtr\fR 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 \fInamePtr\fR
|
|
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 \fInamePtr\fR contains an unknown option name) then NULL
|
|
is returned and an error message is left in \fIinterp\fR's result unless
|
|
\fIinterp\fR is NULL.
|
|
.PP
|
|
\fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted.
|
|
It frees all of the resources associated with any of the configuration
|
|
options defined in \fIrecordPtr\fR by \fIoptionTable\fR.
|
|
.PP
|
|
The \fBTk_Offset\fR macro is provided as a safe way of generating the
|
|
\fIobjOffset\fR and \fIinternalOffset\fR 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.
|
|
.SH "TEMPLATES"
|
|
.PP
|
|
The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR
|
|
via its \fItemplatePtr\fR argument describes the configuration options
|
|
supported by a particular class of widgets. Each structure specifies
|
|
one configuration option and has the following fields:
|
|
.CS
|
|
typedef struct {
|
|
Tk_OptionType \fItype\fR;
|
|
const char *\fIoptionName\fR;
|
|
const char *\fIdbName\fR;
|
|
const char *\fIdbClass\fR;
|
|
const char *\fIdefValue\fR;
|
|
int \fIobjOffset\fR;
|
|
int \fIinternalOffset\fR;
|
|
int \fIflags\fR;
|
|
ClientData \fIclientData\fR;
|
|
int \fItypeMask\fR;
|
|
} \fBTk_OptionSpec\fR;
|
|
.CE
|
|
The \fItype\fR field indicates what kind of configuration option this is
|
|
(e.g. \fBTK_OPTION_COLOR\fR for a color value, or \fBTK_OPTION_INT\fR for
|
|
an integer value). \fIType\fR determines how the
|
|
value of the option is parsed (more on this below).
|
|
The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR;
|
|
it is the name used for the option in Tcl commands and passed to
|
|
procedures via the \fIobjc\fR or \fInamePtr\fR arguments.
|
|
The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR
|
|
to look up a default value for this option in the option database; if
|
|
\fIdbName\fR is NULL then the option database is not used by
|
|
\fBTk_InitOptions\fR for this option. The \fIdefValue\fR field
|
|
specifies a default value for this configuration option if no
|
|
value is specified in the option database. The \fIobjOffset\fR and
|
|
\fIinternalOffset\fR fields indicate where to store the value of this
|
|
option in widget records (more on this below); values for the \fIobjOffset\fR
|
|
and \fIinternalOffset\fR fields should always be generated with the
|
|
\fBTk_Offset\fR macro.
|
|
The \fIflags\fR field contains additional information
|
|
to control the processing of this configuration option (see below
|
|
for details).
|
|
\fIClientData\fR provides additional type-specific data needed
|
|
by certain types. For instance, for \fBTK_OPTION_COLOR\fR types,
|
|
\fIclientData\fR 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, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to
|
|
return information about which options were modified; see the description
|
|
of \fBTk_SetOptions\fR above for details.
|
|
.PP
|
|
When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an
|
|
option into the widget record, they can do it in either of two ways.
|
|
If the \fIobjOffset\fR 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 \fIobjOffset\fR.
|
|
If the \fIinternalOffset\fR 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 \fIinternalOffset\fR. For example, if the option's type is
|
|
\fBTK_OPTION_INT\fR then the internal form is an integer. If the
|
|
\fIobjOffset\fR or \fIinternalOffset\fR 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.
|
|
.PP
|
|
The \fIflags\fR field consists of one or more bits ORed together. At
|
|
present only a single flag is supported: \fBTK_OPTION_NULL_OK\fR. 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 \fBNone\fR, depending on the type of
|
|
the option. If the flag is not set then empty strings will result
|
|
in errors.
|
|
\fBTK_OPTION_NULL_OK\fR is typically used to allow a
|
|
feature to be turned off entirely, e.g. set a cursor value to
|
|
\fBNone\fR so that a window simply inherits its parent's cursor.
|
|
Not all option types support the \fBTK_OPTION_NULL_OK\fR
|
|
flag; for those that do, there is an explicit indication of that fact
|
|
in the descriptions below.
|
|
.PP
|
|
The \fItype\fR field of each Tk_OptionSpec structure determines
|
|
how to parse the value of that configuration option. The
|
|
legal value for \fItype\fR, and the corresponding actions, are
|
|
described below. If the type requires a \fItkwin\fR value to be
|
|
passed into procedures like \fBTk_SetOptions\fR, or if it uses
|
|
the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated
|
|
explicitly; if not mentioned, the type requires neither \fItkwin\fR
|
|
nor \fIclientData\fR.
|
|
.TP
|
|
\fBTK_OPTION_ANCHOR\fR
|
|
The value must be a standard anchor position such as \fBne\fR or
|
|
\fBcenter\fR. The internal form is a Tk_Anchor value like the ones
|
|
returned by \fBTk_GetAnchorFromObj\fR.
|
|
.TP
|
|
\fBTK_OPTION_BITMAP\fR
|
|
The value must be a standard Tk bitmap name. The internal form is a
|
|
Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR.
|
|
This option type requires \fItkwin\fR to be supplied to procedures
|
|
such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
|
|
.TP
|
|
\fBTK_OPTION_BOOLEAN\fR
|
|
The value must be a standard boolean value such as \fBtrue\fR or
|
|
\fBno\fR. The internal form is an integer with value 0 or 1.
|
|
.TP
|
|
\fBTK_OPTION_BORDER\fR
|
|
The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR.
|
|
The internal form is a Tk_3DBorder token like the ones returned
|
|
by \fBTk_Alloc3DBorderFromObj\fR.
|
|
This option type requires \fItkwin\fR to be supplied to procedures
|
|
such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
|
|
.TP
|
|
\fBTK_OPTION_COLOR\fR
|
|
The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR.
|
|
The internal form is an (XColor *) token like the ones returned by
|
|
\fBTk_AllocColorFromObj\fR.
|
|
This option type requires \fItkwin\fR to be supplied to procedures
|
|
such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
|
|
.TP
|
|
\fBTK_OPTION_CURSOR\fR
|
|
The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR.
|
|
The internal form is a Tk_Cursor token like the ones returned by
|
|
\fBTk_AllocCursorFromObj\fR.
|
|
This option type requires \fItkwin\fR to be supplied to procedures
|
|
such as \fBTk_SetOptions\fR, and when the option is set the cursor
|
|
for the window is changed by calling \fBXDefineCursor\fR. This
|
|
option type also supports the \fBTK_OPTION_NULL_OK\fR flag.
|
|
.TP
|
|
\fBTK_OPTION_CUSTOM\fR
|
|
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 \fBCUSTOM OPTION TYPES\fR below for details.
|
|
.TP
|
|
\fBTK_OPTION_DOUBLE\fR
|
|
The string value must be a floating-point number in
|
|
the format accepted by \fBstrtol\fR. The internal form is a C
|
|
\fBdouble\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR
|
|
flag; if a NULL value is set, the internal representation is set to zero.
|
|
.TP
|
|
\fBTK_OPTION_END\fR
|
|
Marks the end of the template. There must be a Tk_OptionSpec structure
|
|
with \fItype\fR \fBTK_OPTION_END\fR at the end of each template. If the
|
|
\fIclientData\fR field of this structure is not NULL, then it points to
|
|
an additional array of Tk_OptionSpec's, which is itself terminated by
|
|
another \fBTK_OPTION_END\fR entry. Templates may be chained arbitrarily
|
|
deeply. This feature allows common options to be shared by several
|
|
widget classes.
|
|
.TP
|
|
\fBTK_OPTION_FONT\fR
|
|
The value must be a standard font name such as \fBTimes 16\fR.
|
|
The internal form is a Tk_Font handle like the ones returned by
|
|
\fBTk_AllocFontFromObj\fR.
|
|
This option type requires \fItkwin\fR to be supplied to procedures
|
|
such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
|
|
.TP
|
|
\fBTK_OPTION_INT\fR
|
|
The string value must be an integer in the format accepted by
|
|
\fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to
|
|
specify octal or hexadecimal numbers, respectively). The internal
|
|
form is a C \fBint\fR value.
|
|
.TP
|
|
\fBTK_OPTION_JUSTIFY\fR
|
|
The value must be a standard justification value such as \fBleft\fR.
|
|
The internal form is a Tk_Justify like the values returned by
|
|
\fBTk_GetJustifyFromObj\fR.
|
|
.TP
|
|
\fBTK_OPTION_PIXELS\fR
|
|
The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR.
|
|
The internal form is an integer value giving a
|
|
distance in pixels, like the values returned by
|
|
\fBTk_GetPixelsFromObj\fR. Note: if the \fIobjOffset\fR field is not
|
|
used then information about the original value of this option will be lost.
|
|
See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. This option
|
|
type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the
|
|
internal representation is set to zero.
|
|
.TP
|
|
\fBTK_OPTION_RELIEF\fR
|
|
The value must be standard relief such as \fBraised\fR.
|
|
The internal form is an integer relief value such as
|
|
\fBTK_RELIEF_RAISED\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR
|
|
flag; if the empty string is specified as the value for the option,
|
|
the integer relief value is set to \fBTK_RELIEF_NULL\fR.
|
|
.TP
|
|
\fBTK_OPTION_STRING\fR
|
|
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 \fBTK_OPTION_NULL_OK\fR flag.
|
|
.TP
|
|
\fBTK_OPTION_STRING_TABLE\fR
|
|
For this type, \fIclientData\fR is a pointer to an array of strings
|
|
suitable for passing to \fBTcl_GetIndexFromObj\fR. 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 \fBTcl_GetStringFromObj\fR.
|
|
.TP
|
|
\fBTK_OPTION_SYNONYM\fR
|
|
This type is used to provide alternative names for an option (for
|
|
example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR).
|
|
The \fBclientData\fR field is a string 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.
|
|
.TP
|
|
\fBTK_OPTION_WINDOW\fR
|
|
The value must be a window path name. The internal form is a
|
|
\fBTk_Window\fR token for the window.
|
|
This option type requires \fItkwin\fR to be supplied to procedures
|
|
such as \fBTk_SetOptions\fR (in order to identify the application),
|
|
and it supports the \fBTK_OPTION_NULL_OK\fR flag.
|
|
.SH "STORAGE MANAGEMENT ISSUES"
|
|
.PP
|
|
If a field of a widget record has its offset stored in the \fIobjOffset\fR
|
|
or \fIinternalOffset\fR 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, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR)
|
|
will automatically free any resources associated with the old value, such as
|
|
Tk_Fonts for \fBTK_OPTION_FONT\fR options or dynamically allocated memory for
|
|
\fBTK_OPTION_STRING\fR options. For an option stored as an object using the
|
|
\fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the
|
|
object pointed to by the \fIobjv\fR value from the call to
|
|
\fBTk_SetOptions\fR. 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
|
|
\fBTk_FreeConfigOptions\fR should be invoked; it will free the resources
|
|
associated with all options and decrement reference counts for any
|
|
objects.
|
|
.PP
|
|
However, the widget code is responsible for storing NULL or \fBNone\fR in
|
|
all pointer and token fields before invoking \fBTk_InitOptions\fR.
|
|
This is needed to allow proper cleanup in the rare case where
|
|
an error occurs in \fBTk_InitOptions\fR.
|
|
.SH "OBJOFFSET VS. INTERNALOFFSET"
|
|
.PP
|
|
In most cases it is simplest to use the \fIinternalOffset\fR field of
|
|
a Tk_OptionSpec structure and not the \fIobjOffset\fR field. This
|
|
makes the internal form of the value immediately available to the
|
|
widget code so the value does not have to be extracted from an object
|
|
each time it is used. However, there are two cases where the
|
|
\fIobjOffset\fR field is useful. The first case is for
|
|
\fBTK_OPTION_PIXELS\fR 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 \fB.b configure \-borderwidth 2m\fR,
|
|
the command \fB.b configure \-borderwidth\fR might return 7, which is the
|
|
integer pixel value corresponding to \fB2m\fR. Unfortunately, this loses
|
|
the original screen-independent value. Thus for \fBTK_OPTION_PIXELS\fR options
|
|
it is better to use the \fIobjOffset\fR 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
|
|
\fIinternalOffset\fR field as well, so that the integer value is
|
|
immediately available for use in the widget code (alternatively,
|
|
\fBTk_GetPixelsFromObj\fR 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 \fBTK_OPTION_PIXELS\fR options.
|
|
.PP
|
|
The second reason to use the \fIobjOffset\fR 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 \fBTK_OPTION_STRING\fR as
|
|
the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field
|
|
but not the \fIinternalOffset\fR field. Then, after calling
|
|
\fBTk_SetOptions\fR, convert the object to internal form yourself.
|
|
.SH "CUSTOM OPTION TYPES"
|
|
.PP
|
|
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 procedures:
|
|
.CS
|
|
typedef struct Tk_ObjCustomOption {
|
|
char *name;
|
|
Tk_CustomOptionSetProc *\fIsetProc\fR;
|
|
Tk_CustomOptionGetProc *\fIgetProc\fR;
|
|
Tk_CustomOptionRestoreProc *\fIrestoreProc\fR;
|
|
Tk_CustomOptionFreeProc *\fIfreeProc\fR;
|
|
ClientData \fIclientData\fR;
|
|
} \fBTk_ObjCustomOption\fR;
|
|
|
|
typedef int \fBTk_CustomOptionSetProc\fR(
|
|
ClientData \fIclientData\fR,
|
|
Tcl_Interp *\fIinterp\fR,
|
|
Tk_Window \fItkwin\fR,
|
|
Tcl_Obj **\fIvaluePtr\fR,
|
|
char *\fIrecordPtr\fR,
|
|
int \fIinternalOffset\fR,
|
|
char *\fIsaveInternalPtr\fR,
|
|
int \fIflags\fR);
|
|
|
|
typedef Tcl_Obj *\fBTk_CustomOptionGetProc\fR(
|
|
ClientData \fIclientData\fR,
|
|
Tk_Window \fItkwin\fR,
|
|
char *\fIrecordPtr\fR,
|
|
int \fIinternalOffset\fR);
|
|
|
|
typedef void \fBTk_CustomOptionRestoreProc\fR(
|
|
ClientData \fIclientData\fR,
|
|
Tk_Window \fItkwin\fR,
|
|
char *\fIinternalPtr\fR,
|
|
char *\fIsaveInternalPtr\fR);
|
|
|
|
typedef void \fBTk_CustomOptionFreeProc\fR(
|
|
ClientData \fIclientData\fR,
|
|
Tk_Window \fItkwin\fR,
|
|
char *\fIinternalPtr\fR);
|
|
.CE
|
|
.PP
|
|
The Tk_ObjCustomOption structure contains six fields: a name
|
|
for the custom option type; pointers to the four procedures; and a
|
|
\fIclientData\fR value to be passed to those procedures when they are
|
|
invoked. The \fIclientData\fR value typically points to a structure
|
|
containing information that is needed by the procedures when they are
|
|
parsing and printing options. \fIRestoreProc\fR and \fIfreeProc\fR
|
|
may be NULL, indicating that no function should be called for those
|
|
operations.
|
|
.PP
|
|
The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to
|
|
convert a Tcl_Obj into an internal representation and store the
|
|
resulting value in the widget record. The arguments are:
|
|
.RS
|
|
.TP
|
|
\fIclientData\fR
|
|
A copy of the \fIclientData\fR field in the Tk_ObjCustomOption
|
|
structure.
|
|
.TP
|
|
\fIinterp\fR
|
|
A pointer to a Tcl interpreter, used for error reporting.
|
|
.TP
|
|
\fITkwin\fR
|
|
A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR
|
|
.TP
|
|
\fIvaluePtr\fR
|
|
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
|
|
\fBTk_SetOptions\fR 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 \fIvaluePtr\fR is the pointer that will be
|
|
stored at the objOffset for the option. \fISetProc\fR may modify the
|
|
value if necessary; for example, \fIsetProc\fR may change the value to
|
|
NULL to support the \fBTK_OPTION_NULL_OK\fR flag.
|
|
.TP
|
|
\fIrecordPtr\fR
|
|
A pointer to the start of the widget record to modify.
|
|
.TP
|
|
\fIinternalOffset\fR
|
|
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.
|
|
.TP
|
|
\fIsaveInternalPtr\fR
|
|
A pointer to storage allocated in a Tk_SavedOptions structure for the
|
|
internal representation of the original option value. Before setting
|
|
the option to its new value, \fIsetProc\fR should set the value
|
|
referenced by \fIsaveInternalPtr\fR to the original value of the
|
|
option in order to support \fBTk_RestoreSavedOptions\fR.
|
|
.TP
|
|
\fIflags\fR
|
|
A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the
|
|
option
|
|
.RE
|
|
.PP
|
|
\fISetProc\fR returns a standard Tcl result: \fBTCL_OK\fR to indicate successful
|
|
processing, or \fBTCL_ERROR\fR to indicate a failure of any kind. An error
|
|
message may be left in the Tcl interpreter given by \fIinterp\fR in
|
|
the case of an error.
|
|
.PP
|
|
The \fIgetProc\fR procedure is invoked by \fBTk_GetOptionValue\fR and
|
|
\fBTk_GetOptionInfo\fR to retrieve a Tcl_Obj representation of the
|
|
internal representation of an option. The \fIclientData\fR argument
|
|
is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
|
|
structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to
|
|
\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIRecordPtr\fR
|
|
is a pointer to the beginning of the widget record to query.
|
|
\fIInternalOffset\fR 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. \fIGetProc\fR must return a pointer to a
|
|
Tcl_Obj representing the value of the option.
|
|
.PP
|
|
The \fIrestoreProc\fR procedure is invoked by
|
|
\fBTk_RestoreSavedOptions\fR to restore a previously saved internal
|
|
representation of a custom option value. The \fIclientData\fR argument
|
|
is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
|
|
structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to
|
|
\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR
|
|
is a pointer to the location where internal representation of the
|
|
option value is stored.
|
|
\fISaveInternalPtr\fR is a pointer to the saved value.
|
|
\fIRestoreProc\fR must copy the value from \fIsaveInternalPtr\fR to
|
|
\fIinternalPtr\fR to restore the value. \fIRestoreProc\fR need not
|
|
free any memory associated with either \fIinternalPtr\fR or
|
|
\fIsaveInternalPtr\fR; \fIfreeProc\fR will be invoked to free that
|
|
memory if necessary. \fIRestoreProc\fR has no return value.
|
|
.PP
|
|
The \fIfreeProc\fR procedure is invoked by \fBTk_SetOptions\fR and
|
|
\fBTk_FreeSavedOptions\fR to free any storage allocated for the
|
|
internal representation of a custom option. The \fIclientData\fR argument
|
|
is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
|
|
structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to
|
|
\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR
|
|
is a pointer to the location where the internal representation of the
|
|
option value is stored. The \fIfreeProc\fR must free any storage
|
|
associated with the option. \fIFreeProc\fR has no return value.
|
|
.SH KEYWORDS
|
|
anchor, bitmap, boolean, border, color, configuration option,
|
|
cursor, double, font, integer, justify,
|
|
pixels, relief, screen distance, synonym
|