summaryrefslogtreecommitdiffstats
path: root/doc/ttk_entry.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ttk_entry.n')
-rw-r--r--doc/ttk_entry.n56
1 files changed, 23 insertions, 33 deletions
diff --git a/doc/ttk_entry.n b/doc/ttk_entry.n
index 66a3651..5275004 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.3 2006/12/13 23:04:33 hobbs Exp $
+'\" RCS: @(#) $Id: ttk_entry.n,v 1.4 2007/10/23 15:44:35 dkf Exp $
'\"
.so man.macros
.TH ttk_entry n 8.5 Tk "Tk Themed Widget"
@@ -24,14 +24,13 @@ 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
@@ -88,8 +87,6 @@ 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
@@ -107,7 +104,6 @@ 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
@@ -138,7 +134,6 @@ entry window.
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:
@@ -220,7 +215,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
@@ -262,19 +257,18 @@ 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 +287,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 +319,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,18 +328,17 @@ 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
@@ -425,7 +418,6 @@ 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 +428,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,9 +436,7 @@ 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