summaryrefslogtreecommitdiffstats
path: root/doc/spinbox.n
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2011-07-18 15:25:38 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2011-07-18 15:25:38 (GMT)
commit55e6d4112ed0b6a5a7ac2f66b05e15647eb10683 (patch)
treecec1bcb89b7f64d9fd6750a9fe013c99cd23bfef /doc/spinbox.n
parent07ec35d561f2b1def36a0a68325ca561055507d0 (diff)
downloadtk-55e6d4112ed0b6a5a7ac2f66b05e15647eb10683.zip
tk-55e6d4112ed0b6a5a7ac2f66b05e15647eb10683.tar.gz
tk-55e6d4112ed0b6a5a7ac2f66b05e15647eb10683.tar.bz2
More small documentation improvements.
Diffstat (limited to 'doc/spinbox.n')
-rw-r--r--doc/spinbox.n80
1 files changed, 41 insertions, 39 deletions
diff --git a/doc/spinbox.n b/doc/spinbox.n
index cc00d58..e88aea6 100644
--- a/doc/spinbox.n
+++ b/doc/spinbox.n
@@ -57,9 +57,9 @@ are specified correctly, the spinbox will use these values to control its
contents. This value must be less than the \fB\-to\fR option.
If \fB\-values\fR is specified, it supercedes this option.
.OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand
-Specifies a script to eval when \fBvalidateCommand\fR returns 0. Setting
+Specifies a script to eval when \fB\-validatecommand\fR returns 0. Setting
it to an empty string disables this feature (the default). The best use of
-this option is to set it to \fIbell\fR. See \fBValidation\fR below for
+this option is to set it to \fIbell\fR. See \fBVALIDATION\fR below for
more information.
.OP \-increment increment Increment
A floating-point value specifying the increment. When used with
@@ -89,16 +89,16 @@ If \fB\-values\fR is specified, it supercedes this option.
Specifies the mode in which validation should operate: \fBnone\fR,
\fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR.
It defaults to \fBnone\fR. When you want validation, you must explicitly
-state which mode you wish to use. See \fBValidation\fR below for more.
+state which mode you wish to use. See \fBVALIDATION\fR below for more.
.OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand
Specifies a script to evaluate when you want to validate the input in the
widget. Setting it to an empty string disables this feature (the default).
Validation occurs according to the value of \fB\-validate\fR.
This command must return a valid Tcl boolean value. If it returns 0 (or
the valid Tcl boolean equivalent) then the value of the widget will not
-change and the \fBinvalidCommand\fR will be evaluated if it is set. If it
+change and the \fB\-invalidcommand\fR will be evaluated if it is set. If it
returns 1, then value will be changed.
-See \fBValidation\fR below for more information.
+See \fBVALIDATION\fR below for more information.
.OP \-values values Values
Must be a proper list value. If specified, the spinbox will use these
values as to control its contents, starting with the first value. This
@@ -129,7 +129,7 @@ to move, or spin, through a fixed set of ascending or descending values
such as times or dates in addition to editing the value as in an
\fBentry\fR. When first created, a spinbox's string is empty.
A portion of the spinbox may be selected as described below.
-If a spinbox is exporting its selection (see the \fBexportSelection\fR
+If a spinbox is exporting its selection (see the \fB\-exportselection\fR
option), then it will observe the standard protocols for handling the
selection; spinbox selections are available as type \fBSTRING\fR.
Spinboxes also observe the standard Tk rules for dealing with the
@@ -141,31 +141,31 @@ Spinboxes are capable of displaying strings that are too long to
fit entirely within the widget's window. In this case, only a
portion of the string will be displayed; commands described below
may be used to change the view in the window. Spinboxes use
-the standard \fBxScrollCommand\fR mechanism for interacting with
-scrollbars (see the description of the \fBxScrollCommand\fR option
+the standard \fB\-xscrollcommand\fR mechanism for interacting with
+scrollbars (see the description of the \fB\-xscrollcommand\fR option
for details). They also support scanning, as described below.
.SH VALIDATION
.PP
-Validation works by setting the \fBvalidateCommand\fR
-option to a script which will be evaluated according to the \fBvalidate\fR
+Validation works by setting the \fB\-validatecommand\fR
+option to a script which will be evaluated according to the \fB\-validate\fR
option as follows:
.PP
.IP \fBnone\fR 10
Default. This means no validation will occur.
.IP \fBfocus\fR 10
-\fBvalidateCommand\fR will be called when the spinbox receives or
+The \fB\-validatecommand\fR will be called when the spinbox receives or
loses focus.
.IP \fBfocusin\fR 10
-\fBvalidateCommand\fR will be called when the spinbox receives focus.
+The \fB\-validatecommand\fR will be called when the spinbox receives focus.
.IP \fBfocusout\fR 10
-\fBvalidateCommand\fR will be called when the spinbox loses focus.
+The \fB\-validatecommand\fR will be called when the spinbox loses focus.
.IP \fBkey\fR 10
-\fBvalidateCommand\fR will be called when the spinbox is edited.
+The \fB\-validatecommand\fR will be called when the spinbox is edited.
.IP \fBall\fR 10
-\fBvalidateCommand\fR will be called for all above conditions.
+The \fB\-validatecommand\fR will be called for all above conditions.
.PP
-It is possible to perform percent substitutions on the \fBvalidateCommand\fR
-and \fBinvalidCommand\fR, just as you would in a \fBbind\fR script. The
+It is possible to perform percent substitutions on the \fB\-validatecommand\fR
+and \fB\-invalidcommand\fR scripts, just as you would in a \fBbind\fR script. The
following substitutions are recognized:
.PP
.IP \fB%d\fR 5
@@ -190,32 +190,32 @@ The type of validation that triggered the callback
.IP \fB%W\fR 5
The name of the spinbox widget.
.PP
-In general, the \fBtextVariable\fR and \fBvalidateCommand\fR can be
+In general, the \fB\-textvariable\fR and \fB\-validatecommand\fR can be
dangerous to mix. Any problems have been overcome so that using the
-\fBvalidateCommand\fR will not interfere with the traditional behavior of
-the spinbox widget. Using the \fBtextVariable\fR for read-only purposes will
+\fB\-validatecommand\fR will not interfere with the traditional behavior of
+the spinbox widget. Using the \fB\-textvariable\fR for read-only purposes will
never cause problems. The danger comes when you try set the
-\fBtextVariable\fR to something that the \fBvalidateCommand\fR would not
-accept, which causes \fBvalidate\fR to become \fInone\fR (the
-\fBinvalidCommand\fR will not be triggered). The same happens
-when an error occurs evaluating the \fBvalidateCommand\fR.
+\fB\-textvariable\fR to something that the \fB\-validatecommand\fR would not
+accept, which causes \fB\-validate\fR to become \fInone\fR (the
+\fB\-invalidcommand\fR will not be triggered). The same happens
+when an error occurs evaluating the \fB\-validatecommand\fR.
.PP
-Primarily, an error will occur when the \fBvalidateCommand\fR or
-\fBinvalidCommand\fR encounters an error in its script while evaluating or
-\fBvalidateCommand\fR does not return a valid Tcl boolean value. The
-\fBvalidate\fR option will also set itself to \fBnone\fR when you edit the
-spinbox widget from within either the \fBvalidateCommand\fR or the
-\fBinvalidCommand\fR. Such editions will override the one that was being
+Primarily, an error will occur when the \fB\-validatecommand\fR or
+\fB\-invalidcommand\fR encounters an error in its script while evaluating or
+\fB\-validatecommand\fR does not return a valid Tcl boolean value. The
+\fB\-validate\fR option will also set itself to \fBnone\fR when you edit the
+spinbox widget from within either the \fB\-validatecommand\fR or the
+\fB\-invalidcommand\fR. Such editions will override the one that was being
validated. If you wish to edit the value of the widget
-during validation and still have the \fBvalidate\fR option set, you should
+during validation and still have the \fB\-validate\fR option set, you should
include the command
.CS
\fI%W config \-validate %v\fR
.CE
-in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you
+in the \fB\-validatecommand\fR or \fB\-invalidcommand\fR (whichever one you
were editing the spinbox widget from). It is also recommended to not set an
-associated \fBtextVariable\fR during validation, as that can cause the
-spinbox widget to become out of sync with the \fBtextVariable\fR.
+associated \fB\-textvariable\fR during validation, as that can cause the
+spinbox widget to become out of sync with the \fB\-textvariable\fR.
.SH "WIDGET COMMAND"
.PP
The \fBspinbox\fR command creates a new Tcl command whose
@@ -392,7 +392,7 @@ Returns an empty string.
Returns 1 if there is are characters selected in the spinbox,
0 if nothing is selected.
.TP
-\fIpathName \fBselection range \fIstart\fR \fIend\fR
+\fIpathName \fBselection range \fIstart end\fR
Sets the selection to include the characters starting with
the one indexed by \fIstart\fR and ending with the one just
before \fIend\fR.
@@ -420,9 +420,9 @@ value, otherwise it just returns the spinbox's string.
If validation is on, it will occur when setting the string.
.TP
\fIpathName \fBvalidate\fR
-This command is used to force an evaluation of the \fBvalidateCommand\fR
-independent of the conditions specified by the \fBvalidate\fR option.
-This is done by temporarily setting the \fBvalidate\fR option to \fBall\fR.
+This command is used to force an evaluation of the \fB\-validatecommand\fR
+independent of the conditions specified by the \fB\-validate\fR option.
+This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR.
It returns 0 or 1.
.TP
\fIpathName \fBxview \fIargs\fR
@@ -441,7 +441,7 @@ in the window, and 40% of the text is off-screen to the right.
These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR
option.
.TP
-\fIpathName \fBxview\fR \fIindex\fR
+\fIpathName \fBxview \fIindex\fR
Adjusts the view in the window so that the character given by \fIindex\fR
is displayed at the left edge of the window.
.TP
@@ -579,6 +579,8 @@ take place.
.PP
The behavior of spinboxes can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
+.SH "SEE ALSO"
+ttk::spinbox(n)
.SH KEYWORDS
spinbox, entry, widget
'\" Local Variables: