summaryrefslogtreecommitdiffstats
path: root/doc/entry.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/entry.n')
-rw-r--r--doc/entry.n103
1 files changed, 99 insertions, 4 deletions
diff --git a/doc/entry.n b/doc/entry.n
index 27c4fcc..4fb806e 100644
--- a/doc/entry.n
+++ b/doc/entry.n
@@ -5,10 +5,10 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: entry.n,v 1.2 1998/09/14 18:22:55 stanton Exp $
+'\" RCS: @(#) $Id: entry.n,v 1.3 1999/12/14 06:51:44 hobbs Exp $
'\"
.so man.macros
-.TH entry n 4.1 Tk "Tk Built-In Commands"
+.TH entry n 8.3 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -24,6 +24,13 @@ entry \- Create and manipulate entry widgets
\-foreground \-insertofftime \-selectborderwidth
.SE
.SH "WIDGET-SPECIFIC OPTIONS"
+.VS 8.3
+.OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand
+Specifies a script to eval when \fBvalidateCommand\fR returns 0.
+Setting it to {} disables this feature (the default). The best use
+of this option is to set it to \fIbell\fR. See \fBValidation\fR
+below for more information.
+.VE
.OP \-show show Show
If this option is specified, then the true contents of the entry
are not displayed in the window.
@@ -39,6 +46,21 @@ Specifies one of two states for the entry: \fBnormal\fR or \fBdisabled\fR.
If the entry is disabled then the value may not be changed using widget
commands and no insertion cursor will be displayed, even if the input focus is
in the widget.
+.VS 8.3
+.OP \-validate validate Validate
+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.
+.OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand
+Specifies a script to eval when you want to validate the input into
+the entry widget. Setting it to {} disables this feature (the default).
+This command must return a valid tcl boolean value. If it returns 0 (or
+the valid tcl boolean equivalent) then it means you reject the new edition
+and it will not occur and the \fBinvalidCommand\fR will be evaluated if it
+is set. If it returns 1, then the new edition occurs.
+See \fBValidation\fR below for more information.
+.VE
.OP \-width width Width
Specifies an integer value indicating the desired width of the entry window,
in average-size characters of the widget's font.
@@ -79,11 +101,77 @@ the standard \fBxScrollCommand\fR mechanism for interacting with
scrollbars (see the description of the \fBxScrollCommand\fR option
for details). They also support scanning, as described below.
+.VS 8.3
+.SH VALIDATION
+.PP
+Validation works by setting the \fBvalidateCommand\fR
+option to a script which will be evaluated according to the \fBvalidate\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 entry receives or
+loses focus.
+.IP \fBfocusin\fR 10
+\fBvalidateCommand\fR will be called when the entry receives focus.
+.IP \fBfocusout\fR 10
+\fBvalidateCommand\fR will be called when the entry loses focus.
+.IP \fBkey\fR 10
+\fBvalidateCommand\fR will be called when the entry is edited.
+.IP \fBall\fR 10
+\fBvalidateCommand\fR will be called for all above conditions.
+.PP
+It is posible to perform percent substitutions on the \fBvalidateCommand\fR
+and \fBinvalidCommand\fR,
+just as you would in a \fBbind\fR script. The following substitutions
+are recognized:
+.PP
+.IP \fB%d\fR 5
+type of action. 1 == INSERT, 0 == DELETE,
+-1 if it's a forced validation or textvariable validation
+.IP \fB%i\fR 5
+index of char string to be added/delete, if any. -1 otherwise
+.IP \fB%P\fR 5
+The value of the entry should edition occur. If you are configuring the
+entry widget to have a new textvariable, this will be the value of that
+textvariable.
+.IP \fB%s\fR 5
+The current value of entry before edition.
+.IP \fB%S\fR 5
+The text string being inserted/deleted, if any, {} otherwise.
+.IP \fB%v\fR 5
+The type of validation currently set.
+.IP \fB%W\fR 5
+The name of the entry widget.
+.PP
+
+In general, the \fBtextVariable\fR and \fBvalidateCommand\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 entry widget. The danger comes when you try set the \fBtextVariable\fR
+to something that the \fBvalidateCommand\fR would not accept. Using the
+\fBtextVariable\fR for read-only purposes will never cause problems.
+Otherwise, the \fBvalidateCommand\fR will turn itself off by setting
+\fBvalidate\fR to \fBnone\fR when an error occurs.
+
+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
+entry widget from within either the \fBvalidateCommand\fR or the
+\fBinvalidCommand\fR. Such editions will override the one that was being
+validated. If you wish to edit the entry widget (for example set it to {})
+during validation and still have the \fBvalidate\fR option set, you should
+include the command "\fIafter idle {%W config -validate %v}\fR" in the
+\fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you were
+editing the entry widget from).
+.VE
+
.SH "WIDGET COMMAND"
.PP
The \fBentry\fR command creates a new Tcl command whose
-name is \fIpathName\fR. This
-command may be used to invoke various
+name is \fIpathName\fR. This command may be used to invoke various
operations on the widget. It has the following general form:
.CS
\fIpathName option \fR?\fIarg arg ...\fR?
@@ -259,6 +347,13 @@ created using the most recent anchor point specified for the widget.
Returns an empty string.
.RE
.TP
+.VS 8.3
+\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. It
+returns 0 or 1.
+.VE
+.TP
\fIpathName \fBxview \fIargs\fR
This command is used to query and change the horizontal position of the
text in the widget's window. It can take any of the following