diff options
Diffstat (limited to 'doc/ttk_entry.n')
| -rw-r--r-- | doc/ttk_entry.n | 87 |
1 files changed, 47 insertions, 40 deletions
diff --git a/doc/ttk_entry.n b/doc/ttk_entry.n index 6df1d82..dcf46fc 100644 --- a/doc/ttk_entry.n +++ b/doc/ttk_entry.n @@ -7,7 +7,7 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" SOURCE: entry.n, r1.12 -'\" RCS: @(#) $Id: ttk_entry.n,v 1.6 2007/10/26 20:13:23 dgp Exp $ +'\" RCS: @(#) $Id: ttk_entry.n,v 1.7 2007/10/29 16:04:14 dkf Exp $ '\" .so man.macros .TH ttk_entry n 8.5 Tk "Tk Themed Widget" @@ -24,9 +24,9 @@ ttk_entry \- Editable text field widget An \fBttk::entry\fR widget displays a one-line text string and allows that string to be edited by the user. The value of the string may be linked to a Tcl variable -with the \fB-textvariable\fR option. +with the \fB\-textvariable\fR option. Entry widgets support horizontal scrolling with the -standard \fB-xscrollcommand\fR option and \fBxview\fR widget command. +standard \fB\-xscrollcommand\fR option and \fBxview\fR widget command. .SO \-class \-cursor \-style \-takefocus \-xscrollcommand @@ -57,7 +57,9 @@ One of \fBleft\fR, \fBcenter\fR, or \fBright\fR. If this option is specified, then the true contents of the entry are not displayed in the window. Instead, each character in the entry's value will be displayed as -the first character in the value of this option, such as ``*''. +the first character in the value of this option, such as +.QW * +or a bullet. This is useful, for example, if the entry is to be used to enter a password. If characters in the entry are selected and copied elsewhere, the @@ -118,8 +120,9 @@ to the first character in the string. .IP \fB@\fInumber\fR In this form, \fInumber\fR is treated as an x-coordinate in the entry's window; the character spanning that x-coordinate is used. -For example, ``\fB@0\fR'' indicates the left-most character in the -window. +For example, +.QW \fB@0\fR +indicates the left-most character in the window. .IP \fBend\fR Indicates the character just after the last one in the entry's string. This is equivalent to specifying a numerical index equal to the length @@ -129,16 +132,18 @@ Indicates the character adjacent to and immediately following the insert cursor. .IP \fBsel.first\fR Indicates the first character in the selection. It is an error to -use this form if the selection isn't in the entry window. +use this form if the selection is not in the entry window. .IP \fBsel.last\fR Indicates the character just after the last one in the selection. -It is an error to use this form if the selection isn't in the +It is an error to use this form if the selection is not in the entry window. .LP -Abbreviations may be used for any of the forms above, e.g. ``\fBe\fR'' -or ``\fBsel.f\fR''. In general, out-of-range indices are automatically -rounded to the nearest legal value. - +Abbreviations may be used for any of the forms above, e.g. +.QW \fBe\fR +or +.QW \fBsel.f\fR . +In general, out-of-range indices are automatically rounded to the +nearest legal value. .SH "WIDGET COMMAND" .PP The following commands are possible for entry widgets: @@ -166,7 +171,7 @@ Delete one or more elements of the entry. \fIFirst\fR is the index of the first character to delete, and \fIlast\fR is the index of the character just after the last one to delete. -If \fIlast\fR isn't specified it defaults to \fIfirst\fR+1, +If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, i.e. a single character is deleted. This command returns the empty string. .TP @@ -199,7 +204,7 @@ has several forms, depending on \fIoption\fR: .TP \fIpathName \fBselection clear\fR Clear the selection if it is currently in this widget. -If the selection isn't in this widget then the command has no effect. +If the selection is not in this widget then the command has no effect. Returns the empty string. .TP \fIpathName \fBselection present\fR @@ -220,7 +225,7 @@ See \fIttk_widget(n)\fR. .TP \fIpathName \fBvalidate\fR Force revalidation, independent of the conditions specified -by the \fB-validate\fR option. +by the \fB\-validate\fR option. Returns 0 if validation fails, 1 if it succeeds. Sets or clears the \fBinvalid\fR state accordingly. .TP @@ -264,17 +269,17 @@ become visible. .RE .SH VALIDATION -The \fB-validate\fR, \fB-validatecommand\fR, and \fB-invalidcommand\fR +The \fB\-validate\fR, \fB\-validatecommand\fR, and \fB\-invalidcommand\fR options are used to enable entry widget validation. .SS "VALIDATION MODES" There are two main validation modes: \fIprevalidation\fR, -in which the \fB-validatecommand\fR is evaluated prior to each edit +in which the \fB\-validatecommand\fR is evaluated prior to each edit and the return value is used to determine whether to accept or reject the change; -and \fIrevalidation\fR, in which the \fB-validatecommand\fR is +and \fIrevalidation\fR, in which the \fB\-validatecommand\fR is evaluated to determine whether the current value is valid. .PP -The \fB-validate\fR option determines when validation occurs; +The \fB\-validate\fR option determines when validation occurs; it may be set to any of the following values: .IP \fBnone\fR Default. This means validation will only occur when @@ -293,30 +298,30 @@ The entry is revalidated when the entry loses focus. .IP \fBall\fR Validation is performed for all above conditions. .PP -The \fB-invalidcommand\fR is evaluated whenever -the \fB-validatecommand\fR returns a false value. +The \fB\-invalidcommand\fR is evaluated whenever +the \fB\-validatecommand\fR returns a false value. .PP -The \fB-validatecommand\fR and \fB-invalidcommand\fR +The \fB\-validatecommand\fR and \fB\-invalidcommand\fR may modify the entry widget's value via the widget \fBinsert\fR or \fBdelete\fR commands, -or by setting the linked \fB-textvariable\fR. +or by setting the linked \fB\-textvariable\fR. If either does so during prevalidation, then the edit is rejected -regardless of the value returned by the \fB-validatecommand\fR. +regardless of the value returned by the \fB\-validatecommand\fR. .PP -If \fB-validatecommand\fR is empty (the default), +If \fB\-validatecommand\fR is empty (the default), validation always succeeds. .SS "VALIDATION SCRIPT SUBSTITUTIONS" It is possible to perform percent substitutions on the -\fB-validatecommand\fR and \fBinvalidCommand\fR, +\fB\-validatecommand\fR and \fBinvalidCommand\fR, just as in a \fBbind\fR script. The following substitutions are recognized: .IP \fB%d\fR Type of action: 1 for \fBinsert\fR prevalidation, 0 for \fBdelete\fR prevalidation, -or -1 for revalidation. +or \-1 for revalidation. .IP \fB%i\fR -Index of character string to be inserted/deleted, if any, otherwise -1. +Index of character string to be inserted/deleted, if any, otherwise \-1. .IP \fB%P\fR In prevalidation, the new value of the entry if the edit is accepted. In revalidation, the current value of the entry. @@ -325,7 +330,7 @@ The current value of entry prior to editing. .IP \fB%S\fR The text string being inserted/deleted, if any, {} otherwise. .IP \fB%v\fR -The current value of the \fB-validate\fR option. +The current value of the \fB\-validate\fR option. .IP \fB%V\fR The validation condition that triggered the callback (\fBkey\fR, \fBfocusin\fR, \fBfocusout\fR, or \fBforced\fR). @@ -334,23 +339,25 @@ The name of the entry widget. .SS "DIFFERENCES FROM TK ENTRY WIDGET VALIDATION" .IP \(bu The standard Tk entry widget automatically disables validation -(by setting \fB-validate\fR to \fBnone\fR) -if the \fB-validatecommand\fR or \fB-invalidcommand\fR modifies +(by setting \fB\-validate\fR to \fBnone\fR) +if the \fB\-validatecommand\fR or \fB\-invalidcommand\fR modifies the entry's value. The Tk themed entry widget only disables validation if one -of the validation scripts raises an error, or if \fB-validatecommand\fR +of the validation scripts raises an error, or if \fB\-validatecommand\fR does not return a valid boolean value. (Thus, it is not necessary to reenable validation after modifying the entry value in a validation script). .IP \(bu The standard entry widget invokes validation whenever the linked -\fB-textvariable\fR is modified; the Tk themed entry widget does not. +\fB\-textvariable\fR is modified; the Tk themed entry widget does not. .SH "DEFAULT BINDINGS" The entry widget's default bindings enable the following behavior. -In the descriptions below, ``word'' refers to a contiguous group -of letters, digits, or ``_'' characters, or any single character -other than these. +In the descriptions below, +.QW word +refers to a contiguous group of letters, digits, or +.QW _ +characters, or any single character other than these. .IP \(bu Clicking mouse button 1 positions the insert cursor just before the character underneath the mouse cursor, sets the @@ -436,17 +443,17 @@ the entry cannot be edited The \fBdisabled\fR state is the same as \fBreadonly\fR, and in addition text cannot be selected. .PP -Note that changes to the linked \fB-textvariable\fR will +Note that changes to the linked \fB\-textvariable\fR will still be reflected in the entry, even if it is disabled or readonly. .PP -Typically, the text is "grayed-out" in the \fBdisabled\fR state, +Typically, the text is +.QW grayed-out +in the \fBdisabled\fR state, and a different background is used in the \fBreadonly\fR state. .PP The entry widget sets the \fBinvalid\fR state if revalidation fails, and clears it whenever validation succeeds. - .SH "SEE ALSO" ttk_widget(n), entry(n) - .SH KEYWORDS entry, widget, text field |