'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: ConfigWidg.3,v 1.8.2.1 2003/10/06 22:15:17 dgp 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_ConfigureWidget 3 4.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_ConfigureWidget 3 4.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_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
.sp
\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR
.SH ARGUMENTS
-.AS Tk_ConfigSpec *widgRec in/out
+.AS char *widgRec in/out
.AP Tcl_Interp *interp in
Interpreter to use for returning error messages.
.AP Tk_Window tkwin in
Window used to represent widget (needed to set up X resources).
-.AP Tk_ConfigSpec *specs in
+.AP "const Tk_ConfigSpec" *specs in
Pointer to table specifying legal configuration options for this
widget.
.AP int argc in
Number of arguments in \fIargv\fR.
-.AP "CONST char" **argv in
+.AP "const char" **argv in
Command-line options for configuring widget.
.AP char *widgRec in/out
Points to widget record structure. Fields in this structure get
.AP int flags in
If non-zero, then it specifies an OR-ed combination of flags that
control the processing of configuration information.
-TK_CONFIG_ARGV_ONLY causes the option database and defaults to be
-ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to
+\fBTK_CONFIG_ARGV_ONLY\fR causes the option database and defaults to be
+ignored, and flag bits \fBTK_CONFIG_USER_BIT\fR and higher are used to
selectively disable entries in \fIspecs\fR.
.AP "type name" type in
The name of the type of a widget record.
.AP "field name" field in
The name of a field in records of type \fItype\fR.
-.AP "CONST char" *argvName in
+.AP "const char" *argvName in
The name used on Tcl command lines to refer to a particular option
(e.g. when creating a widget or invoking the \fBconfigure\fR widget
command). If non-NULL, then information is returned only for this
order to free up resources.
.BE
.SH DESCRIPTION
-.VS 8.1
-.PP
-Note: \fBTk_ConfigureWidget\fP should be replaced with the new
-\fBTcl_Obj\fP based API \fBTk_SetOptions\fP. The old interface is
+.PP
+Note: \fBTk_ConfigureWidget\fR should be replaced with the new
+\fBTcl_Obj\fR based API \fBTk_SetOptions\fR. The old interface is
retained for backward compatibility.
-.VE
.PP
\fBTk_ConfigureWidget\fR is called to configure various aspects of a
widget, such as colors, fonts, border width, etc.
\fIargv\fR) to fill in fields of a record (\fIwidgRec\fR).
It uses the option database and defaults specified in \fIspecs\fR
to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR.
-\fBTk_ConfigureWidget\fR normally returns the value TCL_OK; in this
+\fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this
case it does not modify \fIinterp\fR.
If an error
-occurs then TCL_ERROR is returned and \fBTk_ConfigureWidget\fR will
-leave an error message in \fIinterp->result\fR in the standard Tcl
+occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will
+leave an error message in interpreter \fIinterp\fR's result in the standard Tcl
fashion.
In the event of an error return, some of the fields of \fIwidgRec\fR
could already have been set, if configuration information for them
option and has the following structure:
.CS
typedef struct {
- int \fItype\fR;
- char *\fIargvName\fR;
- char *\fIdbName\fR;
- char *\fIdbClass\fR;
- char *\fIdefValue\fR;
- int \fIoffset\fR;
- int \fIspecFlags\fR;
- Tk_CustomOption *\fIcustomPtr\fR;
-} Tk_ConfigSpec;
+ int \fItype\fR;
+ const char *\fIargvName\fR;
+ const char *\fIdbName\fR;
+ const char *\fIdbClass\fR;
+ const char *\fIdefValue\fR;
+ int \fIoffset\fR;
+ int \fIspecFlags\fR;
+ const Tk_CustomOption *\fIcustomPtr\fR;
+} \fBTk_ConfigSpec\fR;
.CE
The \fItype\fR field indicates what type of configuration option this is
-(e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for
+(e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for
an integer value). The \fItype\fR field indicates how to use the
value of the option (more on this below).
-The \fIargvName\fR field is a string such as ``\-font'' or ``\-bg'',
+The \fIargvName\fR field is a string such as
+.QW \-font
+or
+.QW \-bg ,
which is compared with the values in \fIargv\fR (if \fIargvName\fR is
-NULL it means this is a grouped entry; see GROUPED ENTRIES below). The
+NULL it means this is a grouped entry; see \fBGROUPED ENTRIES\fR below). The
\fIdbName\fR and \fIdbClass\fR fields are used to look up a value
for this option in the option database. The \fIdefValue\fR field
specifies a default value for this configuration option if no
to control the processing of this configuration option (see FLAGS
below).
The last field, \fIcustomPtr\fR, is only used if \fItype\fR is
-TK_CONFIG_CUSTOM; see CUSTOM OPTION TYPES below.
+\fBTK_CONFIG_CUSTOM\fR; see CUSTOM OPTION TYPES below.
.PP
\fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which
(if any) configuration options are specified there. \fIArgv\fR
Finally, if no entry is found in the option database, the
\fIdefValue\fR field of the \fIspecs\fR entry is used as the
value for the configuration option. If the \fIdefValue\fR is
-NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in
+NULL, or if the \fBTK_CONFIG_DONT_SET_DEFAULT\fR bit is set in
\fIflags\fR, then there is no default value and this \fIspecs\fR entry
will be ignored if no value is specified in \fIargv\fR or the
option database.
.PP
Once a string value has been determined for a configuration option,
\fBTk_ConfigureWidget\fR translates the string value into a more useful
-form, such as a color if \fItype\fR is TK_CONFIG_COLOR or an integer
-if \fItype\fR is TK_CONFIG_INT. This value is then stored in the
+form, such as a color if \fItype\fR is \fBTK_CONFIG_COLOR\fR or an integer
+if \fItype\fR is \fBTK_CONFIG_INT\fR. This value is then stored in the
record pointed to by \fIwidgRec\fR. This record is assumed to
contain information relevant to the manager of the widget; its exact
type is unknown to \fBTk_ConfigureWidget\fR. The \fIoffset\fR field
the information about this configuration option. You should use the
\fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for
a description of \fBTk_Offset\fR). The location indicated by
-\fIwidgRec\fR and \fIoffset\fR will be referred to as the ``target''
+\fIwidgRec\fR and \fIoffset\fR will be referred to as the
+.QW target
in the descriptions below.
.PP
The \fItype\fR field of each entry in \fIspecs\fR determines what
\fBTk_GetCursor\fR and the result is stored in the target.
In addition, the resulting cursor is made the active cursor
for \fItkwin\fR by calling \fBXDefineCursor\fR.
-If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target and \fItkwin\fR's
active cursor will be set to \fBNone\fR.
If the previous value of the target
-wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
+was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
.TP
\fBTK_CONFIG_ANCHOR\fR
The value must be an ASCII string identifying an anchor point in one of the ways
suitable for passing to \fBTk_GetBitmap\fR. The value is converted
to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result
is stored in the target.
-If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target is set to \fBNone\fR.
If the previous value of the target
-wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
+was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
.TP
\fBTK_CONFIG_BOOLEAN\fR
The value must be an ASCII string specifying a boolean value. Any
-of the values ``true'', ``yes'', ``on'', or ``1'',
+of the values
+.QW true ,
+.QW yes ,
+.QW on ,
+or
+.QW 1 ,
or an abbreviation of one of these values, means true;
-any of the values ``false'', ``no'', ``off'', or ``0'', or an abbreviation of
-one of these values, means false.
+any of the values
+.QW false ,
+.QW no ,
+.QW off ,
+or
+.QW 0 ,
+or an abbreviation of one of these values, means false.
The target is expected to be an integer; for true values it will
be set to 1 and for false values it will be set to 0.
.TP
suitable for passing to \fBTk_Get3DBorder\fR. The value is converted
to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result
is stored in the target.
-If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to NULL.
If the previous value of the target
-wasn't NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
+was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
.TP
\fBTK_CONFIG_CAP_STYLE\fR
The value must be
suitable for passing to \fBTk_GetColor\fR. The value is converted
to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result
is stored in the target.
-If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to \fBNone\fR.
If the previous value of the target
-wasn't NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
+was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
.TP
\fBTK_CONFIG_CURSOR\fR
This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except
This option allows applications to define new option types.
The \fIcustomPtr\fR field of the entry points to a structure
defining the new option type.
-See the section CUSTOM OPTION TYPES below for details.
+See the section \fBCUSTOM OPTION TYPES\fR below for details.
.TP
\fBTK_CONFIG_DOUBLE\fR
The value must be an ASCII floating-point number in
suitable for passing to \fBTk_GetFont\fR. The value is converted
to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result
is stored in the target.
-If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to NULL.
If the previous value of the target
-wasn't NULL, then it is freed by passing it to \fBTk_FreeFont\fR.
+was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR.
.TP
\fBTK_CONFIG_INT\fR
The value must be an ASCII integer string
-in the format accepted by \fBstrtol\fR (e.g. ``0''
-and ``0x'' prefixes may be used to specify octal or hexadecimal
+in the format accepted by \fBstrtol\fR (e.g.
+.QW 0
+and
+.QW 0x
+prefixes may be used to specify octal or hexadecimal
numbers, respectively). The string is converted to an integer
value and the integer is stored in the target.
.TP
\fBTK_CONFIG_STRING\fR
A copy
of the value is made by allocating memory space with
-\fBmalloc\fR and copying the value into the dynamically-allocated
+\fBTcl_Alloc\fR and copying the value into the dynamically-allocated
space. A pointer to the new string is stored in the target.
-If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to NULL.
-If the previous value of the target wasn't NULL, then it is
-freed by passing it to \fBfree\fR.
+If the previous value of the target was not NULL, then it is
+freed by passing it to \fBTcl_Free\fR.
.TP
\fBTK_CONFIG_SYNONYM\fR
This \fItype\fR value identifies special entries in \fIspecs\fR that
are synonyms for other entries. If an \fIargv\fR value matches the
-\fIargvName\fR of a TK_CONFIG_SYNONYM entry, the entry isn't used
+\fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used
directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR
for another entry whose \fIargvName\fR is the same as the \fIdbName\fR
-field in the TK_CONFIG_SYNONYM entry; this new entry is used just
+field in the \fBTK_CONFIG_SYNONYM\fR entry; this new entry is used just
as if its \fIargvName\fR had matched the \fIargv\fR value. The
synonym mechanism allows multiple \fIargv\fR values to be used for
-a single configuration option, such as ``\-background'' and ``\-bg''.
+a single configuration option, such as
+.QW \-background
+and
+.QW \-bg .
.TP
\fBTK_CONFIG_UID\fR
The value is translated to a \fBTk_Uid\fR
(by passing it to \fBTk_GetUid\fR). The resulting value
is stored in the target.
-If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR and the value
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR and the value
is an empty string then the target will be set to NULL.
.TP
\fBTK_CONFIG_WINDOW\fR
The value must be a window path name. It is translated to a
\fBTk_Window\fR token and the token is stored in the target.
-
.SH "GROUPED ENTRIES"
.PP
In some cases it is useful to generate multiple resources from
a single configuration value. For example, a color name might
be used both to generate the background color for a widget (using
-TK_CONFIG_COLOR) and to generate a 3-D border to draw around the
-widget (using TK_CONFIG_BORDER). In cases like this it is possible
+\fBTK_CONFIG_COLOR\fR) and to generate a 3-D border to draw around the
+widget (using \fBTK_CONFIG_BORDER\fR). In cases like this it is possible
to specify that several consecutive entries in \fIspecs\fR are to
be treated as a group. The first entry is used to determine a value
(using its \fIargvName\fR, \fIdbName\fR,
\fIargvName\fR field; this indicates that the entry is to be grouped
with the entry that precedes it. Only the \fItype\fR and \fIoffset\fR
fields are used from these follow-on entries.
-
.SH "FLAGS"
.PP
The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used
described below.
.PP
First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has
-the TK_CONFIG_ARGV_ONLY bit set (i.e., \fIflags\fR | TK_CONFIG_ARGV_ONLY != 0),
+the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0),
then the option database and
\fIdefValue\fR fields are not used. In this case, if an entry in
-\fIspecs\fR doesn't match a field in \fIargv\fR then nothing happens:
-the corresponding target isn't modified. This feature is useful
+\fIspecs\fR does not match a field in \fIargv\fR then nothing happens:
+the corresponding target is not modified. This feature is useful
when the goal is to modify certain configuration options while
leaving others in their current state, such as when a \fBconfigure\fR
widget command is being processed.
This flag 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.
-If this bit isn't set then empty strings are processed as strings,
+If this bit is not set then empty strings are processed as strings,
which generally results in an error.
.TP
\fBTK_CONFIG_DONT_SET_DEFAULT\fR
\fBTk_ConfigureWidget\fR.
.TP
\fBTK_CONFIG_OPTION_SPECIFIED\fR
-This bit is set and cleared by \fBTk_ConfigureWidget\fR. Whenever
-\fBTk_ConfigureWidget\fR returns, this bit will be set in all the
-entries where a value was specified in \fIargv\fR.
-It will be zero in all other entries.
-This bit provides a way for clients to determine which values
-actually changed in a call to \fBTk_ConfigureWidget\fR.
+This bit is
+deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR
+so that callers could detect what entries were specified in
+\fIargv\fR, but it was removed because it was inherently
+thread-unsafe. Code that wishes to detect what options were specified
+should use \fBTk_SetOptions\fR instead.
.PP
-The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically
+The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically
used to specify different default values for
monochrome and color displays. This is done by creating two
entries in \fIspecs\fR that are identical except for their
\fIdefValue\fR and \fIspecFlags\fR fields. One entry should have
-the value TK_CONFIG_MONO_ONLY in its \fIspecFlags\fR and the
+the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the
default value for monochrome displays in its \fIdefValue\fR; the
-other entry entry should have the value TK_CONFIG_COLOR_ONLY in
+other entry should have the value \fBTK_CONFIG_COLOR_ONLY\fR in
its \fIspecFlags\fR and the appropriate \fIdefValue\fR for
color displays.
.PP
options for all the widget types. When processing a particular
widget type, only entries relevant to that type will be used. This
effect is achieved by setting the high-order bits (those in positions
-equal to or greater than TK_CONFIG_USER_BIT) in \fIspecFlags\fR
+equal to or greater than \fBTK_CONFIG_USER_BIT\fR) in \fIspecFlags\fR
values or in \fIflags\fR. In order for a particular entry in
\fIspecs\fR to be used, its high-order bits must match exactly
the high-order bits of the \fIflags\fR value passed to
\fIflags\fR will have a single one of these bits set to select the
entries for the desired widget type. For a working example of
this feature, see the code in tkButton.c.
-
.SH TK_OFFSET
.PP
The \fBTk_Offset\fR macro is provided as a safe way of generating
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 TK_CONFIGUREINFO
.PP
The \fBTk_ConfigureInfo\fR procedure may be used to obtain
a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument,
\fBTk_ConfigureInfo\fR generates a string describing all of the
configuration options for the window. The string is placed
-in \fIinterp->result\fR. Under normal circumstances
-it returns TCL_OK; if an error occurs then it returns TCL_ERROR
-and \fIinterp->result\fR contains an error message.
+in interpreter \fIinterp\fR's result. Under normal circumstances
+it returns \fBTCL_OK\fR; if an error occurs then it returns \fBTCL_ERROR\fR
+and the interpreter's result will contain an error message.
.PP
If \fIargvName\fR is NULL, then the value left in
-\fIinterp->result\fR by \fBTk_ConfigureInfo\fR
+the interpreter's result by \fBTk_ConfigureInfo\fR
consists of a list of one or more entries, each of which describes
one configuration option (i.e. one entry in \fIspecs\fR). Each
entry in the list will contain either two or five values. If the
-corresponding entry in \fIspecs\fR has type TK_CONFIG_SYNONYM, then
+corresponding entry in \fIspecs\fR has type \fBTK_CONFIG_SYNONYM\fR, then
the list will contain two values: the \fIargvName\fR for the entry
and the \fIdbName\fR (synonym name). Otherwise the list will contain
five values: \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR,
.PP
If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL,
then it indicates a single option, and information is returned only
-for that option. The string placed in \fIinterp->result\fR will be
+for that option. The string placed in the interpreter's result will be
a list containing two or five values as described above; this will
be identical to the corresponding sublist that would have been returned
if \fIargvName\fR had been NULL.
.PP
The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict
the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR.
-
.SH TK_CONFIGUREVALUE
.PP
\fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR;
instead of returning a list of values, it just returns the current value
of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL).
-The value is returned in \fIinterp->result\fR and TCL_OK is
+The value is returned in interpreter \fIinterp\fR's result and \fBTCL_OK\fR is
normally returned as the procedure's result.
If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is
-not a valid option name), TCL_ERROR is returned and an error message
-is left in \fIinterp->result\fR.
+not a valid option name), \fBTCL_ERROR\fR is returned and an error message
+is left in the interpreter's result.
This procedure is typically called to implement \fBcget\fR widget
commands.
-
.SH TK_FREEOPTIONS
.PP
The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup
to release all of the resources associated with configuration options.
It scans through \fIspecs\fR and for each entry corresponding to a
resource that must be explicitly freed (e.g. those with
-type TK_CONFIG_COLOR), it frees the resource in the widget record.
-If the field in the widget record doesn't refer to a resource (e.g.
+type \fBTK_CONFIG_COLOR\fR), it frees the resource in the widget record.
+If the field in the widget record does not refer to a resource (e.g.
it contains a null pointer) then no resource is freed for that
entry.
After freeing a resource, \fBTk_FreeOptions\fR sets the
corresponding field of the widget record to null.
-
.SH "CUSTOM OPTION TYPES"
.PP
Applications can extend the built-in configuration types with additional
of the a type and creating a structure pointing to those procedures:
.CS
typedef struct Tk_CustomOption {
- Tk_OptionParseProc *\fIparseProc\fR;
- Tk_OptionPrintProc *\fIprintProc\fR;
- ClientData \fIclientData\fR;
-} Tk_CustomOption;
+ Tk_OptionParseProc *\fIparseProc\fR;
+ Tk_OptionPrintProc *\fIprintProc\fR;
+ ClientData \fIclientData\fR;
+} \fBTk_CustomOption\fR;
-typedef int Tk_OptionParseProc(
- ClientData \fIclientData\fR,
- Tcl_Interp *\fIinterp\fR,
- Tk_Window \fItkwin\fR,
- char *\fIvalue\fR,
- char *\fIwidgRec\fR,
- int \fIoffset\fR);
+typedef int \fBTk_OptionParseProc\fR(
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ Tk_Window \fItkwin\fR,
+ char *\fIvalue\fR,
+ char *\fIwidgRec\fR,
+ int \fIoffset\fR);
-typedef char *Tk_OptionPrintProc(
- ClientData \fIclientData\fR,
- Tk_Window \fItkwin\fR,
- char *\fIwidgRec\fR,
- int \fIoffset\fR,
- Tcl_FreeProc **\fIfreeProcPtr\fR);
+typedef const char *\fBTk_OptionPrintProc\fR(
+ ClientData \fIclientData\fR,
+ Tk_Window \fItkwin\fR,
+ char *\fIwidgRec\fR,
+ int \fIoffset\fR,
+ Tcl_FreeProc **\fIfreeProcPtr\fR);
.CE
The Tk_CustomOption structure contains three fields, which are pointers
to the two procedures and a \fIclientData\fR value to be passed to those
of the widget record to the location where the option value is to
be placed. The procedure should translate the string to whatever
form is appropriate for the option and store the value in the widget
-record. It should normally return TCL_OK, but if an error occurs
-in translating the string to a value then it should return TCL_ERROR
-and store an error message in \fIinterp->result\fR.
+record. It should normally return \fBTCL_OK\fR, but if an error occurs
+in translating the string to a value then it should return \fBTCL_ERROR\fR
+and store an error message in interpreter \fIinterp\fR's result.
.PP
The \fIprintProc\fR procedure is called
by \fBTk_ConfigureInfo\fR to produce a string value describing an
Once \fIparseProc\fR and \fIprintProc\fR have been defined and a
Tk_CustomOption structure has been created for them, options of this
new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR
-fields are TK_CONFIG_CUSTOM and whose \fIcustomPtr\fR fields point
+fields are \fBTK_CONFIG_CUSTOM\fR and whose \fIcustomPtr\fR fields point
to the Tk_CustomOption structure.
-
.SH EXAMPLES
.PP
Although the explanation of \fBTk_ConfigureWidget\fR is fairly
(tkFrame.c) has a simple configuration table, and the library
implementation of buttons (tkButton.c) has a much more complex
table that uses many of the fancy \fIspecFlags\fR mechanisms.
-
.SH "SEE ALSO"
Tk_SetOptions(3)
-
.SH KEYWORDS
anchor, bitmap, boolean, border, cap style, color, configuration options,
cursor, custom, double, font, integer, join style, justify, millimeters,
OSDN Git Service
