diff options
Diffstat (limited to 'doc/entry.n')
| -rw-r--r-- | doc/entry.n | 103 |
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 |