'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: SetOptions.3,v 1.8 2000/10/01 21:31:35 ericm Exp $
-'\"
-'\" The definitions below are for supplemental macros used in Tcl/Tk
-'\" manual entries.
-'\"
-'\" .AP type name in/out ?indent?
-'\" Start paragraph describing an argument to a library procedure.
-'\" type is type of argument (int, etc.), in/out is either "in", "out",
-'\" or "in/out" to describe whether procedure reads or modifies arg,
-'\" and indent is equivalent to second arg of .IP (shouldn't ever be
-'\" needed; use .AS below instead)
-'\"
-'\" .AS ?type? ?name?
-'\" Give maximum sizes of arguments for setting tab stops. Type and
-'\" name are examples of largest possible arguments that will be passed
-'\" to .AP later. If args are omitted, default tab stops are used.
-'\"
-'\" .BS
-'\" Start box enclosure. From here until next .BE, everything will be
-'\" enclosed in one large box.
-'\"
-'\" .BE
-'\" End of box enclosure.
-'\"
-'\" .CS
-'\" Begin code excerpt.
-'\"
-'\" .CE
-'\" End code excerpt.
-'\"
-'\" .VS ?version? ?br?
-'\" Begin vertical sidebar, for use in marking newly-changed parts
-'\" of man pages. The first argument is ignored and used for recording
-'\" the version when the .VS was added, so that the sidebars can be
-'\" found and removed when they reach a certain age. If another argument
-'\" is present, then a line break is forced before starting the sidebar.
-'\"
-'\" .VE
-'\" End of vertical sidebar.
-'\"
-'\" .DS
-'\" Begin an indented unfilled display.
-'\"
-'\" .DE
-'\" End of indented unfilled display.
-'\"
-'\" .SO
-'\" Start of list of standard options for a Tk widget. The
-'\" options follow on successive lines, in four columns separated
-'\" by tabs.
-'\"
-'\" .SE
-'\" End of list of standard options for a Tk widget.
-'\"
-'\" .OP cmdName dbName dbClass
-'\" Start of description of a specific option. cmdName gives the
-'\" option's name as specified in the class command, dbName gives
-'\" the option's name in the option database, and dbClass gives
-'\" the option's class in the option database.
-'\"
-'\" .UL arg1 arg2
-'\" Print arg1 underlined, then print arg2 normally.
-'\"
-'\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
-'\"
-'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
+.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
+.\" The -*- nroff -*- definitions below are for supplemental macros used
+.\" in Tcl/Tk manual entries.
+.\"
+.\" .AP type name in/out ?indent?
+.\" Start paragraph describing an argument to a library procedure.
+.\" type is type of argument (int, etc.), in/out is either "in", "out",
+.\" or "in/out" to describe whether procedure reads or modifies arg,
+.\" and indent is equivalent to second arg of .IP (shouldn't ever be
+.\" needed; use .AS below instead)
+.\"
+.\" .AS ?type? ?name?
+.\" Give maximum sizes of arguments for setting tab stops. Type and
+.\" name are examples of largest possible arguments that will be passed
+.\" to .AP later. If args are omitted, default tab stops are used.
+.\"
+.\" .BS
+.\" Start box enclosure. From here until next .BE, everything will be
+.\" enclosed in one large box.
+.\"
+.\" .BE
+.\" End of box enclosure.
+.\"
+.\" .CS
+.\" Begin code excerpt.
+.\"
+.\" .CE
+.\" End code excerpt.
+.\"
+.\" .VS ?version? ?br?
+.\" Begin vertical sidebar, for use in marking newly-changed parts
+.\" of man pages. The first argument is ignored and used for recording
+.\" the version when the .VS was added, so that the sidebars can be
+.\" found and removed when they reach a certain age. If another argument
+.\" is present, then a line break is forced before starting the sidebar.
+.\"
+.\" .VE
+.\" End of vertical sidebar.
+.\"
+.\" .DS
+.\" Begin an indented unfilled display.
+.\"
+.\" .DE
+.\" End of indented unfilled display.
+.\"
+.\" .SO ?manpage?
+.\" Start of list of standard options for a Tk widget. The manpage
+.\" argument defines where to look up the standard options; if
+.\" omitted, defaults to "options". The options follow on successive
+.\" lines, in three columns separated by tabs.
+.\"
+.\" .SE
+.\" End of list of standard options for a Tk widget.
+.\"
+.\" .OP cmdName dbName dbClass
+.\" Start of description of a specific option. cmdName gives the
+.\" option's name as specified in the class command, dbName gives
+.\" the option's name in the option database, and dbClass gives
+.\" the option's class in the option database.
+.\"
+.\" .UL arg1 arg2
+.\" Print arg1 underlined, then print arg2 normally.
+.\"
+.\" .QW arg1 ?arg2?
+.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
+.\"
+.\" .PQ arg1 ?arg2?
+.\" Print an open parenthesis, arg1 in quotes, then arg2 normally
+.\" (for trailing punctuation) and then a closing parenthesis.
+.\"
+.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
-'\" # Start an argument description
+.\" # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
-\&\\$1 \\fI\\$2\\fP (\\$3)
+\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.\}
.\}
..
-'\" # define tabbing values for .AP
+.\" # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
-'\" # BS - start boxed text
-'\" # ^y = starting y location
-'\" # ^b = 1
+.\" # BS - start boxed text
+.\" # ^y = starting y location
+.\" # ^b = 1
.de BS
.br
.mk ^y
.if n \l'\\n(.lu\(ul'
.if n .fi
..
-'\" # BE - end boxed text (draw box now)
+.\" # BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.br
.nr ^b 0
..
-'\" # VS - start vertical sidebar
-'\" # ^Y = starting y location
-'\" # ^v = 1 (for troff; for nroff this doesn't matter)
+.\" # VS - start vertical sidebar
+.\" # ^Y = starting y location
+.\" # ^v = 1 (for troff; for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
-'\" # VE - end of vertical sidebar
+.\" # VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.\}
.nr ^v 0
..
-'\" # Special macro to handle page bottom: finish off current
-'\" # box/sidebar if in box/sidebar mode, then invoked standard
-'\" # page bottom macro.
+.\" # Special macro to handle page bottom: finish off current
+.\" # box/sidebar if in box/sidebar mode, then invoked standard
+.\" # page bottom macro.
.de ^B
.ev 2
'ti 0
.mk ^Y
.\}
..
-'\" # DS - begin display
+.\" # DS - begin display
.de DS
.RS
.nf
.sp
..
-'\" # DE - end display
+.\" # DE - end display
.de DE
.fi
.RE
.sp
..
-'\" # SO - start of list of standard options
+.\" # SO - start of list of standard options
.de SO
+'ie '\\$1'' .ds So \\fBoptions\\fR
+'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
-'\" # SE - end of list of standard options
+.\" # SE - end of list of standard options
.de SE
.fi
.ft R
.LP
-See the \\fBoptions\\fR manual entry for details on the standard options.
+See the \\*(So manual entry for details on the standard options.
..
-'\" # OP - start of full description for a single option
+.\" # OP - start of full description for a single option
.de OP
.LP
.nf
.fi
.IP
..
-'\" # CS - begin code excerpt
+.\" # CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
-'\" # CE - end code excerpt
+.\" # CE - end code excerpt
.de CE
.fi
.RE
..
+.\" # UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
-.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
+.\" # QW - apply quotation marks to word
+.de QW
+.ie '\\*(lq'"' ``\\$1''\\$2
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\$2
+..
+.\" # PQ - apply parens and quotation marks to word
+.de PQ
+.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
+.\"" fix emacs highlighting
+.el (\\*(lq\\$1\\*(rq\\$2)\\$3
+..
+.\" # QR - quoted range
+.de QR
+.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
+..
+.\" # MT - "empty" string
+.de MT
+.QW ""
+..
.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
int
\fBTk_Offset(\fItype, field\fB)\fR
.SH ARGUMENTS
-.AS Tk_SavedOptions "*CONST objv[]" in/out
+.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 Tk_OptionSpec *templatePtr in
+.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.
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 TK_OPTION_COLOR, this argument indicates
+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
+.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
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
+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 an \fBtkButton.c\fR.
+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
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 TCL_OK. If an error occurred while setting the default values
-(e.g., because a default value was erroneous) then TCL_ERROR is returned
+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
-isn't NULL.
+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
\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 TCL_OK. If
+\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 TCL_ERROR is returned and an error message is left in
-\fIinterp\fR's result if \fIinterp\fR isn't NULL.
+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 isn't NULL then it points to an integer
+\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
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 doesn't redisplay the widget
-if the modified options don't affect the widget's appearance.
+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
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
one configuration option and has the following fields:
.CS
typedef struct {
- Tk_OptionType \fItype\fR;
- char *\fIoptionName\fR;
- char *\fIdbName\fR;
- char *\fIdbClass\fR;
- char *\fIdefValue\fR;
- int \fIobjOffset\fR;
- int \fIinternalOffset\fR;
- int \fIflags\fR;
- ClientData \fIclientData\fR;
- int \fItypeMask\fR;
-} Tk_OptionSpec;
+ 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;
+ const void *\fIclientData\fR;
+ int \fItypeMask\fR;
+} \fBTk_OptionSpec\fR;
.CE
The \fItype\fR field indicates what kind of configuration option this is
-(e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for
+(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;
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 TK_OPTION_COLOR types,
+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.
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
-TK_OPTION_INT then the internal form is an integer. If the
+\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: TK_OPTION_NULL_OK. If
+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.
-TK_OPTION_NULL_OK is typically used to allow a
+\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 TK_OPTION_NULL_OK
+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 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 TK_OPTION_NULL_OK flag.
+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
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 TK_OPTION_NULL_OK flag.
+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 TK_OPTION_NULL_OK flag.
+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.
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 TK_OPTION_NULL_OK flag.
+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 CUSTOM OPTION TYPES below for details.
+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 TK_OPTION_NULL_OK
+\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 TK_OPTION_END at the end of each template. If the
-\fIclientData\fR field of this structure isn't NULL, then it points to
+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 TK_OPTION_END entry. Templates may be chained arbitrarily
+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
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 TK_OPTION_NULL_OK flag.
+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
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 isn't
+\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 TK_OPTION_NULL_OK flag; if a NULL value is set, the
+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
-TK_RELIEF_RAISED. This option type supports the TK_OPTION_NULL_OK
+\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 TK_RELIEF_NULL.
+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 TK_OPTION_NULL_OK flag.
+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
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.
+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 (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.
+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 TK_OPTION_NULL_OK flag.
-
+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
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 TK_OPTION_FONT options or dynamically allocated memory for
-TK_OPTION_STRING options. For an option stored as an object using the
+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
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 doesn't have to be extracted from an object
+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
-TK_OPTION_PIXELS options. In this case, the internal form is
+\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 TK_OPTION_PIXELS options
+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 field as well, so that the integer value is
+\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 TK_OPTION_PIXELS options.
+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 TK_OPTION_STRING as
+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
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;
-} 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 Tk_CustomOptionSetProc(
- 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 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 *Tk_CustomOptionGetProc(
- ClientData \fIclientData\fR,
- Tk_Window \fItkwin\fR,
- char *\fIrecordPtr\fR,
- int \fIinternalOffset\fR);
+typedef Tcl_Obj *\fBTk_CustomOptionGetProc\fR(
+ ClientData \fIclientData\fR,
+ Tk_Window \fItkwin\fR,
+ char *\fIrecordPtr\fR,
+ int \fIinternalOffset\fR);
-typedef void Tk_CustomOptionRestoreProc(
- ClientData \fIclientData\fR,
- Tk_Window \fItkwin\fR,
- char *\fIinternalPtr\fR,
- char *\fIsaveInternalPtr\fR);
+typedef void \fBTk_CustomOptionRestoreProc\fR(
+ ClientData \fIclientData\fR,
+ Tk_Window \fItkwin\fR,
+ char *\fIinternalPtr\fR,
+ char *\fIsaveInternalPtr\fR);
-typedef void Tk_CustomOptionFreeProc(
- ClientData \fIclientData\fR,
- Tk_Window \fItkwin\fR,
- char *\fIinternalPtr\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
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 TK_OPTION_NULL_OK flag.
+NULL to support the \fBTK_OPTION_NULL_OK\fR flag.
.TP
\fIrecordPtr\fR
A pointer to the start of the widget record to modify.
option
.RE
.PP
-\fISetProc\fR returns a standard Tcl result: TCL_OK to indicate successful
-processing, or TCL_ERROR to indicate a failure of any kind. An error
+\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
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,
OSDN Git Service
