* doc/CrtItemType.3: fixed docs for Tk_CreateItemType to reflect

	changes made in 8.3.0 (but old style would still work as well).
	[Bug: 4252]
	* doc/entry.n: improved docs discussing caveats and gotchas when
	mixing textvar with widget validation

2 files changed, 43 insertions, 33 deletions

diff --git a/doc/CrtItemType.3 b/doc/CrtItemType.3
index 0ed1bdc..442f242 100644
--- a/doc/CrtItemType.3
+++ b/doc/CrtItemType.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtItemType.3,v 1.4 1999/04/21 21:53:20 rjohnson Exp $
+'\" RCS: @(#) $Id: CrtItemType.3,v 1.5 2000/03/02 21:53:00 hobbs Exp $
 '\" 
 .so man.macros
 .TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures"
@@ -185,8 +185,8 @@ typedef int Tk_ItemCreateProc(
 	Tcl_Interp *\fIinterp\fR,
 	Tk_Canvas \fIcanvas\fR,
 	Tk_Item *\fIitemPtr\fR,
-	int \fIargc\fR,
-	char **\fIargv\fR);
+	int \fIobjc\fR,
+	Tcl_Obj* CONST \fIobjv\fR);
 .CE
 The \fIinterp\fR argument is the interpreter in which the canvas's
 \fBcreate\fR widget command was invoked, and \fIcanvas\fR is a
@@ -195,17 +195,17 @@ handle for the canvas widget.
 size \fItypePtr->itemSize\fR.
 Tk has already initialized the item's header (the first
 \fBsizeof(Tk_ItemType)\fR bytes).
-The \fIargc\fR and \fIargv\fR arguments describe all of the
+The \fIobjc\fR and \fIobjv\fR arguments describe all of the
 arguments to the \fBcreate\fR command after the \fItype\fR
 argument.
 For example, in the widget command
 .CS
 \fB\&.c create rectangle 10 20 50 50 \-fill black\fR
 .CE
-\fIargc\fR will be \fB6\fR and \fIargv\fR[0] will contain the
-string \fB10\fR.
+\fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the
+integer object \fB10\fR.
 .PP
-\fIcreateProc\fR should use \fIargc\fR and \fIargv\fR to initialize
+\fIcreateProc\fR should use \fIobjc\fR and \fIobjv\fR to initialize
 the type-specific parts of the item record and set an initial value
 for the bounding box in the item's header.
 It should return a standard Tcl completion code and leave an
@@ -241,21 +241,21 @@ typedef int Tk_ItemConfigureProc(
 	Tcl_Interp *\fIinterp\fR,
 	Tk_Canvas \fIcanvas\fR,
 	Tk_Item *\fIitemPtr\fR,
-	int \fIargc\fR,
-	char **\fIargv\fR,
+	int \fIobjc\fR,
+	Tcl_Obj* CONST \fIobjv\fR,
 	int \fIflags\fR);
 .CE
-The \fIinterp\fR argument identifies the interpreter in which the
+The \fIinterp\fR objument identifies the interpreter in which the
 widget command was invoked,  \fIcanvas\fR is a handle for the canvas
 widget, and \fIitemPtr\fR is a pointer to the item being configured.
-\fIargc\fR and \fIargv\fR contain the configuration options.  For
+\fIobjc\fR and \fIobjv\fR contain the configuration options.  For
 example, if the following command is invoked:
 .CS
 \fB\&.c itemconfigure 2 \-fill red \-outline black\fR
 .CE
-\fIargc\fR is \fB4\fR and \fIargv\fR contains the strings \fB\-fill\fR
+\fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR
 through \fBblack\fR.
-\fIargc\fR will always be an even value.
+\fIobjc\fR will always be an even value.
 The  \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR;
 currently this value is always TK_CONFIG_ARGV_ONLY when Tk
 invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR
@@ -276,17 +276,17 @@ typedef int Tk_ItemCoordProc(
 	Tcl_Interp *\fIinterp\fR,
 	Tk_Canvas \fIcanvas\fR,
 	Tk_Item *\fIitemPtr\fR,
-	int \fIargc\fR,
-	char **\fIargv\fR);
+	int \fIobjc\fR,
+	Tcl_Obj* CONST \fIobjv\fR);
 .CE
 The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
-all have the standard meanings, and \fIargc\fR and \fIargv\fR
+all have the standard meanings, and \fIobjc\fR and \fIobjv\fR
 describe the coordinate arguments.
 For example, if the following widget command is invoked:
 .CS
 \fB\&.c coords 2 30 90\fR
 .CE
-\fIargc\fR will be \fB2\fR and \fBargv\fR will contain the string values
+\fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects
 \fB30\fR and \fB90\fR.
 .PP
 The \fIcoordProc\fR procedure should process the new coordinates,
diff --git a/doc/entry.n b/doc/entry.n
index 4fb806e..ee76524 100644
--- a/doc/entry.n
+++ b/doc/entry.n
@@ -1,11 +1,12 @@
 '\"
 '\" Copyright (c) 1990-1994 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1998-2000 Scriptics Corporation.
 '\"
 '\" 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.3 1999/12/14 06:51:44 hobbs Exp $
+'\" RCS: @(#) $Id: entry.n,v 1.4 2000/03/02 21:53:01 hobbs Exp $
 '\" 
 .so man.macros
 .TH entry n 8.3 Tk "Tk Built-In Commands"
@@ -128,10 +129,10 @@ 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
+Type of action: 1 for \fBinsert\fR, 0 for \fBdelete\fR,
+or -1 for focus, forced or textvariable validation.
 .IP \fB%i\fR 5
-index of char string to be added/delete, if any. -1 otherwise
+Index of char string to be inserted/deleted, if any, otherwise -1.
 .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
@@ -142,19 +143,22 @@ The current value of entry before edition.
 The text string being inserted/deleted, if any, {} otherwise.
 .IP \fB%v\fR 5
 The type of validation currently set.
+.IP \fB%V\fR 5
+The type of validation that triggered the callback
+(key, focusin, focusout, forced).
 .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.
-
+the entry widget.  Using the \fBtextVariable\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.
+.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
@@ -163,9 +167,14 @@ 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).
+include the command
+.CS
+     \fIafter idle {%W config -validate %v}\fR
+.CE
+in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you
+were editing the entry widget from).  It is also recommended to not set an
+associated \fBtextVariable\fR during validation, as that can cause the
+entry widget to become out of sync with the \fBtextVariable\fR.
 .VE
 
 .SH "WIDGET COMMAND"
@@ -350,8 +359,9 @@ Returns an empty string.
 .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.
+independent of the conditions specified by the \fBvalidate\fR option.
+This is done by temporarily setting the \fBvalidate\fR option to \fBall\fR.
+It returns 0 or 1.
 .VE
 .TP
 \fIpathName \fBxview \fIargs\fR