* doc/canvas.n: added docs for items added by dash patch (-*dash*,

	-state, -active*, -disabled*, -offset, essentially rewrote the
	man patch for completely updated 8.3 canvas widget.
	* doc/entry.n: added docs for entry widget validation
	* doc/event.n: added docs for -warp
	* doc/text.n: doc'ed new -state value 'hidden'
	* doc/GetDash.3: (new file) man page explaining Tk_GetDash

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