1ttk::entry(n) Tk Themed Widget ttk::entry(n)
2______________________________________________________________________________
6
8 ttk::entry - Editable text field widget
9
11 ttk::entry pathName ?options?
12______________________________________________________________________________
13
15 An ttk::entry widget displays a one-line text string and allows that
16 string to be edited by the user. The value of the string may be linked
17 to a Tcl variable with the -textvariable option. Entry widgets support
18 horizontal scrolling with the standard -xscrollcommand option and xview
19 widget command.
20
22 -class -cursor
23 -font -foreground
24 -style
25 -takefocus -xscrollcommand
26 See the ttk_widget manual entry for details on the standard options.
28
30 Command-Line Name:-exportselection
31 Database Name: exportSelection
32 Database Class: ExportSelection
33 A boolean value specifying whether or not a selection in the
35 widget should be linked to the X selection. If the selection is
36 exported, then selecting in the widget deselects the current X
37 selection, selecting outside the widget deselects any widget se‐
38 lection, and the widget will respond to selection retrieval re‐
39 quests when it has a selection.
40 Command-Line Name:-invalidcommand
42 Database Name: invalidCommand
43 Database Class: InvalidCommand
44 A script template to evaluate whenever the -validatecommand re‐
46 turns 0. See VALIDATION below for more information.
47 Command-Line Name:-justify
49 Database Name: justify
50 Database Class: Justify
51 Specifies how the text is aligned within the entry widget. One
53 of left, center, or right.
54 Command-Line Name:-show
56 Database Name: show
57 Database Class: Show
58 If this option is specified, then the true contents of the entry
60 are not displayed in the window. Instead, each character in the
61 entry's value will be displayed as the first character in the
62 value of this option, such as “*” or a bullet. This is useful,
63 for example, if the entry is to be used to enter a password. If
64 characters in the entry are selected and copied elsewhere, the
65 information copied will be what is displayed, not the true con‐
66 tents of the entry.
67 Command-Line Name:-state
69 Database Name: state
70 Database Class: State
71 Compatibility option; see ttk::widget(n) for details. Specifies
73 one of three states for the entry, normal, disabled, or read‐
74 only. See WIDGET STATES, below.
75 Command-Line Name:-textvariable
77 Database Name: textVariable
78 Database Class: Variable
79 Specifies the name of a global variable whose value is linked to
81 the entry widget's contents. Whenever the variable changes
82 value, the widget's contents are updated, and vice versa.
83 Command-Line Name:-validate
85 Database Name: validate
86 Database Class: Validate
87 Specifies the mode in which validation should operate: none, fo‐
89 cus, focusin, focusout, key, or all. Default is none, meaning
90 that validation is disabled. See VALIDATION below.
91 Command-Line Name:-validatecommand
93 Database Name: validateCommand
94 Database Class: ValidateCommand
95 A script template to evaluate whenever validation is triggered.
97 If set to the empty string (the default), validation is dis‐
98 abled. The script must return a boolean value. See VALIDATION
99 below.
100 Command-Line Name:-width
102 Database Name: width
103 Database Class: Width
104 Specifies an integer value indicating the desired width of the
106 entry window, in average-size characters of the widget's font.
107
109 A portion of the entry may be selected as described below. If an entry
110 is exporting its selection (see the -exportselection option), then it
111 will observe the standard X11 protocols for handling the selection;
112 entry selections are available as type STRING. Entries also observe
113 the standard Tk rules for dealing with the input focus. When an entry
114 has the input focus it displays an insert cursor to indicate where new
115 characters will be inserted.
116 Entries are capable of displaying strings that are too long to fit en‐
118 tirely within the widget's window. In this case, only a portion of the
119 string will be displayed; commands described below may be used to
120 change the view in the window. Entries use the standard -xscrollcom‐
121 mand mechanism for interacting with scrollbars (see the description of
122 the -xscrollcommand option for details).
123
125 Many of the entry widget commands take one or more indices as argu‐
126 ments. An index specifies a particular character in the entry's
127 string, in any of the following ways:
128 number Specifies the character as a numerical index, where 0 corre‐
130 sponds to the first character in the string.
131 @number
133 In this form, number is treated as an x-coordinate in the en‐
134 try's window; the character spanning that x-coordinate is used.
135 For example, “@0” indicates the left-most character in the win‐
136 dow.
137 end Indicates the character just after the last one in the entry's
139 string. This is equivalent to specifying a numerical index
140 equal to the length of the entry's string.
141 insert Indicates the character adjacent to and immediately following
143 the insert cursor.
144 sel.first
146 Indicates the first character in the selection. It is an error
147 to use this form if the selection is not in the entry window.
148 sel.last
150 Indicates the character just after the last one in the selec‐
151 tion. It is an error to use this form if the selection is not
152 in the entry window.
153 Abbreviations may be used for any of the forms above, e.g. “e” or
155 “sel.l”. In general, out-of-range indices are automatically rounded to
156 the nearest legal value.
157
159 The following subcommands are possible for entry widgets:
160 pathName bbox index
162 Returns a list of four numbers describing the bounding box of
163 the character given by index. The first two elements of the
164 list give the x and y coordinates of the upper-left corner of
165 the screen area covered by the character (in pixels relative to
166 the widget) and the last two elements give the width and height
167 of the character, in pixels. The bounding box may refer to a
168 region outside the visible area of the window.
169 pathName delete first ?last?
171 Delete one or more elements of the entry. First is the index of
172 the first character to delete, and last is the index of the
173 character just after the last one to delete. If last is not
174 specified it defaults to first+1, i.e. a single character is
175 deleted. This command returns the empty string.
176 pathName get
178 Returns the entry's string.
179 pathName icursor index
181 Arrange for the insert cursor to be displayed just before the
182 character given by index. Returns the empty string.
183 pathName index index
185 Returns the numerical index corresponding to index.
186 pathName insert index string
188 Insert string just before the character indicated by index. Re‐
189 turns the empty string.
190 pathName selection option arg
192 This command is used to adjust the selection within an entry.
193 It has several forms, depending on option:
194 pathName selection clear
196 Clear the selection if it is currently in this widget.
197 If the selection is not in this widget then the command
198 has no effect. Returns the empty string.
199 pathName selection present
201 Returns 1 if there is are characters selected in the en‐
202 try, 0 if nothing is selected.
203 pathName selection range start end
205 Sets the selection to include the characters starting
206 with the one indexed by start and ending with the one
207 just before end. If end refers to the same character as
208 start or an earlier one, then the entry's selection is
209 cleared.
210 pathName validate
212 Force revalidation, independent of the conditions specified by
213 the -validate option. Returns 0 if validation fails, 1 if it
214 succeeds. Sets or clears the invalid state accordingly. See
215 VALIDATION below for more details.
216 The entry widget also supports the following generic ttk::widget widget
218 subcommands (see ttk::widget(n) for details):
219 cget configure identify
221 instate state xview
222
225 The -validate, -validatecommand, and -invalidcommand options are used
226 to enable entry widget validation.
227 VALIDATION MODES
229 There are two main validation modes: prevalidation, in which the -vali‐
230 datecommand is evaluated prior to each edit and the return value is
231 used to determine whether to accept or reject the change; and revalida‐
232 tion, in which the -validatecommand is evaluated to determine whether
233 the current value is valid.
234 The -validate option determines when validation occurs; it may be set
236 to any of the following values:
237 none Default. This means validation will only occur when
239 specifically requested by the validate widget command.
240 key The entry will be prevalidated prior to each edit
242 (specifically, whenever the insert or delete widget com‐
243 mands are called). If prevalidation fails, the edit is
244 rejected.
245 focus The entry is revalidated when the entry receives or loses
247 focus.
248 focusin
250 The entry is revalidated when the entry receives focus.
251 focusout
253 The entry is revalidated when the entry loses focus.
254 all Validation is performed for all above conditions.
256 The -invalidcommand is evaluated whenever the -validatecommand returns
258 a false value.
259 The -validatecommand and -invalidcommand may modify the entry widget's
261 value via the widget insert or delete commands, or by setting the
262 linked -textvariable. If either does so during prevalidation, then the
263 edit is rejected regardless of the value returned by the -validatecom‐
264 mand.
265 If -validatecommand is empty (the default), validation always succeeds.
267 VALIDATION SCRIPT SUBSTITUTIONS
269 It is possible to perform percent substitutions on the -validatecommand
270 and -invalidcommand, just as in a bind script. The following substitu‐
271 tions are recognized:
272 %d Type of action: 1 for insert prevalidation, 0 for delete
274 prevalidation, or -1 for revalidation.
275 %i Index of character string to be inserted/deleted, if any,
277 otherwise -1.
278 %P In prevalidation, the new value of the entry if the edit
280 is accepted. In revalidation, the current value of the
281 entry.
282 %s The current value of entry prior to editing.
284 %S The text string being inserted/deleted, if any, {} other‐
286 wise.
287 %v The current value of the -validate option.
289 %V The validation condition that triggered the callback
291 (key, focusin, focusout, or forced).
292 %W The name of the entry widget.
294 DIFFERENCES FROM TK ENTRY WIDGET VALIDATION
296 The standard Tk entry widget automatically disables validation (by set‐
297 ting -validate to none) if the -validatecommand or -invalidcommand mod‐
298 ifies the entry's value. The Tk themed entry widget only disables val‐
299 idation if one of the validation scripts raises an error, or if -vali‐
300 datecommand does not return a valid boolean value. (Thus, it is not
301 necessary to re-enable validation after modifying the entry value in a
302 validation script).
303 In addition, the standard entry widget invokes validation whenever the
305 linked -textvariable is modified; the Tk themed entry widget does not.
306
308 The entry widget's default bindings enable the following behavior. In
309 the descriptions below, “word” refers to a contiguous group of letters,
310 digits, or “_” characters, or any single character other than these.
311 • Clicking mouse button 1 positions the insert cursor just before the
313 character underneath the mouse cursor, sets the input focus to this
314 widget, and clears any selection in the widget. Dragging with
315 mouse button 1 down strokes out a selection between the insert cur‐
316 sor and the character under the mouse.
317 • Double-clicking with mouse button 1 selects the word under the
319 mouse and positions the insert cursor at the end of the word.
320 Dragging after a double click strokes out a selection consisting of
321 whole words.
322 • Triple-clicking with mouse button 1 selects all of the text in the
324 entry and positions the insert cursor at the end of the line.
325 • The ends of the selection can be adjusted by dragging with mouse
327 button 1 while the Shift key is down. If the button is double-
328 clicked before dragging then the selection will be adjusted in
329 units of whole words.
330 • Clicking mouse button 1 with the Control key down will position the
332 insert cursor in the entry without affecting the selection.
333 • If any normal printing characters are typed in an entry, they are
335 inserted at the point of the insert cursor.
336 • The view in the entry can be adjusted by dragging with the middle
338 mouse button (button 2, or button 3 in TkAqua). If the middle mouse
339 button is clicked without moving the mouse, the selection is copied
340 into the entry at the position of the mouse cursor.
341 • If the mouse is dragged out of the entry on the left or right sides
343 while button 1 is pressed, the entry will automatically scroll to
344 make more text visible (if there is more text off-screen on the
345 side where the mouse left the window).
346 • The Left and Right keys move the insert cursor one character to the
348 left or right; they also clear any selection in the entry. If
349 Left or Right is typed with the Shift key down, then the insertion
350 cursor moves and the selection is extended to include the new char‐
351 acter. Control-Left and Control-Right move the insert cursor by
352 words, and Control-Shift-Left and Control-Shift-Right move the in‐
353 sert cursor by words and also extend the selection. Control-b and
354 Control-f behave the same as Left and Right, respectively.
355 • The Home key and Control-a move the insert cursor to the beginning
357 of the entry and clear any selection in the entry. Shift-Home
358 moves the insert cursor to the beginning of the entry and extends
359 the selection to that point.
360 • The End key and Control-e move the insert cursor to the end of the
362 entry and clear any selection in the entry. Shift-End moves the
363 cursor to the end and extends the selection to that point.
364 • Control-/ selects all the text in the entry.
366 • Control-\ clears any selection in the entry.
368 • The standard Tk <<Cut>>, <<Copy>>, <<Paste>>, and <<Clear>> virtual
370 events operate on the selection in the expected manner.
371 • The Delete key deletes the selection, if there is one in the entry.
373 If there is no selection, it deletes the character to the right of
374 the insert cursor.
375 • The BackSpace key and Control-h delete the selection, if there is
377 one in the entry. If there is no selection, it deletes the charac‐
378 ter to the left of the insert cursor.
379 • Control-d deletes the character to the right of the insert cursor.
381 • Control-k deletes all the characters to the right of the insertion
383 cursor.
384
386 In the disabled state, the entry cannot be edited and the text cannot
387 be selected. In the readonly state, no insert cursor is displayed and
388 the entry cannot be edited (specifically: the insert and delete com‐
389 mands have no effect). The disabled state is the same as readonly, and
390 in addition text cannot be selected.
391 Note that changes to the linked -textvariable will still be reflected
393 in the entry, even if it is disabled or readonly.
394 Typically, the text is “grayed-out” in the disabled state, and a dif‐
396 ferent background is used in the readonly state.
397 The entry widget sets the invalid state if revalidation fails, and
399 clears it whenever validation succeeds.
400
402 The class name for a ttk::entry is TEntry.
403 Dynamic states: disabled, focus, readonly.
405 TEntry styling options configurable with ttk::style are:
407 -background color
409 For backwards compatibility, when using the aqua theme (for
410 macOS), this option behaves as an alias for the -fieldbackground
411 provided that no value is specified for -fieldbackground. Other‐
412 wise it is ignored.
413 -bordercolor color
414 -darkcolor color
415 -fieldbackground color
416 Some themes use a graphical background and their field back‐
417 ground colors cannot be changed.
418 -foreground color
419 -insertcolor color
420 -insertwidth amount
421 -lightcolor color
422 -padding padding
423 -relief relief
424 -selectbackground color
425 -selectborderwidth amount
426 -selectforeground color
427 See the ttk::style manual page for information on how to configure ttk
429 styles.
430
432 ttk::widget(n), entry(n)
433
435 entry, widget, text field
436Tk 8.5 ttk::entry(n)