diff options
Diffstat (limited to 'doc/ttk_entry.n')
| -rw-r--r-- | doc/ttk_entry.n | 82 |
1 files changed, 42 insertions, 40 deletions
diff --git a/doc/ttk_entry.n b/doc/ttk_entry.n index 2e3a306..6df1d82 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.5 2007/10/24 14:32:59 dkf Exp $ +'\" RCS: @(#) $Id: ttk_entry.n,v 1.6 2007/10/26 20:13:23 dgp Exp $ '\" .so man.macros .TH ttk_entry n 8.5 Tk "Tk Themed Widget" @@ -24,13 +24,14 @@ 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 +\-class \-cursor \-style \-takefocus +\-xscrollcommand .SE + .SH "WIDGET-SPECIFIC OPTIONS" .OP \-exportselection exportSelection ExportSelection A boolean value specifying whether or not @@ -56,9 +57,7 @@ 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 -.QW * -or a bullet character. +the first character in the value of this option, such as ``*''. 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 @@ -89,6 +88,8 @@ Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. .\" Not in ttk: If the value is less than or equal to zero, the widget picks a .\" Not in ttk: size just large enough to hold its current text. +.BE + .SH NOTES A portion of the entry may be selected as described below. If an entry is exporting its selection (see the \fBexportSelection\fR @@ -106,6 +107,7 @@ may be used to change the view in the window. Entries use the standard \fBxScrollCommand\fR mechanism for interacting with scrollbars (see the description of the \fBxScrollCommand\fR option for details). + .SH "INDICES" Many of the \fBentry\fR widget commands take one or more indices as arguments. An index specifies a particular character in the entry's @@ -116,9 +118,8 @@ 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, -.QW \fB@0\fR -indicates the left-most character in the window. +For example, ``\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 @@ -134,12 +135,10 @@ 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 entry window. .LP -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. +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. + .SH "WIDGET COMMAND" .PP The following commands are possible for entry widgets: @@ -221,7 +220,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 @@ -263,18 +262,19 @@ If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right 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,22 +293,22 @@ 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 @@ -325,7 +325,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,24 +334,23 @@ 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, -.QW word -refers to a contiguous group of letters, digits, or -.QW _ -characters, or any single character other than these. +In the descriptions below, ``word'' refers to a contiguous group +of letters, digits, or ``_'' 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 @@ -426,6 +425,7 @@ Control-d deletes the character to the right of the insert cursor. .IP \(bu Control-k deletes all the characters to the right of the insertion cursor. + .SH "WIDGET STATES" In the \fBdisabled\fR state, the entry cannot be edited and the text cannot be selected. @@ -436,7 +436,7 @@ 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, @@ -444,7 +444,9 @@ 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 |