1entry(n) Tk Built-In Commands entry(n)
2______________________________________________________________________________
6
8 entry - Create and manipulate 'entry' one-line text entry widgets
9
11 entry pathName ?options?
12
14 -background -highlightthickness -selectbackground
15 -borderwidth -insertbackground -selectborderwidth
16 -cursor -insertborderwidth -selectforeground
17 -exportselection -insertofftime -takefocus
18 -font -insertontime -textvariable
19 -foreground -insertwidth -xscrollcommand
20 -highlightbackground -justify
21 -highlightcolor -relief
22 See the options manual entry for details on the standard options.
24
26 Command-Line Name:-disabledbackground
27 Database Name: disabledBackground
28 Database Class: DisabledBackground
29 Specifies the background color to use when the entry is dis‐
31 abled. If this option is the empty string, the normal back‐
32 ground color is used.
33 Command-Line Name:-disabledforeground
35 Database Name: disabledForeground
36 Database Class: DisabledForeground
37 Specifies the foreground color to use when the entry is dis‐
39 abled. If this option is the empty string, the normal fore‐
40 ground color is used.
41 Command-Line Name:-invalidcommand or -invcmd
43 Database Name: invalidCommand
44 Database Class: InvalidCommand
45 Specifies a script to eval when -validatecommand returns 0.
47 Setting it to {} disables this feature (the default). The best
48 use of this option is to set it to bell. See VALIDATION below
49 for more information.
50 Command-Line Name:-readonlybackground
52 Database Name: readonlyBackground
53 Database Class: ReadonlyBackground
54 Specifies the background color to use when the entry is read‐
56 only. If this option is the empty string, the normal background
57 color is used.
58 Command-Line Name:-show
60 Database Name: show
61 Database Class: Show
62 If this option is specified, then the true contents of the entry
64 are not displayed in the window. Instead, each character in the
65 entry's value will be displayed as the first character in the
66 value of this option, such as “*”. This is useful, for example,
67 if the entry is to be used to enter a password. If characters
68 in the entry are selected and copied elsewhere, the information
69 copied will be what is displayed, not the true contents of the
70 entry.
71 Command-Line Name:-state
73 Database Name: state
74 Database Class: State
75 Specifies one of three states for the entry: normal, disabled,
77 or readonly. If the entry is readonly, then the value may not
78 be changed using widget commands and no insertion cursor will be
79 displayed, even if the input focus is in the widget; the con‐
80 tents of the widget may still be selected. If the entry is dis‐
81 abled, the value may not be changed, no insertion cursor will be
82 displayed, the contents will not be selectable, and the entry
83 may be displayed in a different color, depending on the values
84 of the -disabledforeground and -disabledbackground options.
85 Command-Line Name:-validate
87 Database Name: validate
88 Database Class: Validate
89 Specifies the mode in which validation should operate: none, fo‐
91 cus, focusin, focusout, key, or all. It defaults to none. When
92 you want validation, you must explicitly state which mode you
93 wish to use. See VALIDATION below for more.
94 Command-Line Name:-validatecommand or -vcmd
96 Database Name: validateCommand
97 Database Class: ValidateCommand
98 Specifies a script to eval when you want to validate the input
100 into the entry widget. Setting it to {} disables this feature
101 (the default). This command must return a valid Tcl boolean
102 value. If it returns 0 (or the valid Tcl boolean equivalent)
103 then it means you reject the new edition and it will not occur
104 and the -invalidcommand will be evaluated if it is set. If it
105 returns 1, then the new edition occurs. See VALIDATION below
106 for more information.
107 Command-Line Name:-width
109 Database Name: width
110 Database Class: Width
111 Specifies an integer value indicating the desired width of the
113 entry window, in average-size characters of the widget's font.
114 If the value is less than or equal to zero, the widget picks a
115 size just large enough to hold its current text.
116______________________________________________________________________________
117
119 The entry command creates a new window (given by the pathName argument)
120 and makes it into an entry widget. Additional options, described
121 above, may be specified on the command line or in the option database
122 to configure aspects of the entry such as its colors, font, and relief.
123 The entry command returns its pathName argument. At the time this com‐
124 mand is invoked, there must not exist a window named pathName, but
125 pathName's parent must exist.
126 An entry is a widget that displays a one-line text string and allows
128 that string to be edited using widget commands described below, which
129 are typically bound to keystrokes and mouse actions. When first cre‐
130 ated, an entry's string is empty. A portion of the entry may be se‐
131 lected as described below. If an entry is exporting its selection (see
132 the -exportselection option), then it will observe the standard X11
133 protocols for handling the selection; entry selections are available
134 as type STRING. Entries also observe the standard Tk rules for dealing
135 with the input focus. When an entry has the input focus it displays an
136 insertion cursor to indicate where new characters will be inserted.
137 Entries are capable of displaying strings that are too long to fit en‐
139 tirely within the widget's window. In this case, only a portion of the
140 string will be displayed; commands described below may be used to
141 change the view in the window. Entries use the standard -xscrollcom‐
142 mand mechanism for interacting with scrollbars (see the description of
143 the -xscrollcommand option for details). They also support scanning,
144 as described below.
145
147 Validation works by setting the -validatecommand option to a script
148 (validateCommand) which will be evaluated according to the -validate
149 option as follows:
150 none Default. This means no validation will occur.
152 focus validateCommand will be called when the entry receives or
154 loses focus.
155 focusin validateCommand will be called when the entry receives focus.
157 focusout validateCommand will be called when the entry loses focus.
159 key validateCommand will be called when the entry is edited.
161 all validateCommand will be called for all above conditions.
163 It is possible to perform percent substitutions on the value of the
165 -validatecommand and -invalidcommand options, just as you would in a
166 bind script. The following substitutions are recognized:
167 %d Type of action: 1 for insert, 0 for delete, or -1 for focus,
169 forced or textvariable validation.
170 %i Index of char string to be inserted/deleted, if any, otherwise -1.
172 %P The value of the entry if the edit is allowed. If you are config‐
174 uring the entry widget to have a new textvariable, this will be
175 the value of that textvariable.
176 %s The current value of entry prior to editing.
178 %S The text string being inserted/deleted, if any, {} otherwise.
180 %v The type of validation currently set.
182 %V The type of validation that triggered the callback (key, focusin,
184 focusout, forced).
185 %W The name of the entry widget.
187 In general, the -textvariable and -validatecommand options can be dan‐
189 gerous to mix. Any problems have been overcome so that using the -val‐
190 idatecommand will not interfere with the traditional behavior of the
191 entry widget. Using the -textvariable for read-only purposes will
192 never cause problems. The danger comes when you try set the -textvari‐
193 able to something that the -validatecommand would not accept, which
194 causes -validate to become none (the -invalidcommand will not be trig‐
195 gered). The same happens when an error occurs evaluating the -vali‐
196 datecommand.
197 Primarily, an error will occur when the -validatecommand or -invalid‐
199 command encounters an error in its script while evaluating or -vali‐
200 datecommand does not return a valid Tcl boolean value. The -validate
201 option will also set itself to none when you edit the entry widget from
202 within either the -validatecommand or the -invalidcommand. Such edi‐
203 tions will override the one that was being validated. If you wish to
204 edit the entry widget (for example set it to {}) during validation and
205 still have the -validate option set, you should include the command
206 after idle {%W config -validate %v}
207 in the -validatecommand or -invalidcommand (whichever one you were
208 editing the entry widget from). It is also recommended to not set an
209 associated -textvariable during validation, as that can cause the entry
210 widget to become out of sync with the -textvariable.
211
213 The entry command creates a new Tcl command whose name is pathName.
214 This command may be used to invoke various operations on the widget.
215 It has the following general form:
216 pathName subcommand ?arg arg ...?
217 Subcommand and the args determine the exact behavior of the command.
218 INDICES
220 Many of the widget commands for entries take one or more indices as ar‐
221 guments. An index specifies a particular character in the entry's
222 string, in any of the following ways:
223 number Specifies the character as a numerical index, where 0 cor‐
225 responds to the first character in the string.
226 anchor Indicates the anchor point for the selection, which is set
228 with the select from and select adjust widget commands.
229 end Indicates the character just after the last one in the en‐
231 try's string. This is equivalent to specifying a numerical
232 index equal to the length of the entry's string.
233 insert Indicates the character adjacent to and immediately follow‐
235 ing the insertion cursor.
236 sel.first Indicates the first character in the selection. It is an
238 error to use this form if the selection is not in the entry
239 window.
240 sel.last Indicates the character just after the last one in the se‐
242 lection. It is an error to use this form if the selection
243 is not in the entry window.
244 @number In this form, number is treated as an x-coordinate in the
246 entry's window; the character spanning that x-coordinate
247 is used. For example, “@0” indicates the left-most charac‐
248 ter in the window.
249 Abbreviations may be used for any of the forms above, e.g. “e” or
251 “sel.f”. In general, out-of-range indices are automatically rounded to
252 the nearest legal value.
253 SUBCOMMANDS
255 The following commands are possible for entry widgets:
256 pathName bbox index
258 Returns a list of four numbers describing the bounding box of
259 the character given by index. The first two elements of the
260 list give the x and y coordinates of the upper-left corner of
261 the screen area covered by the character (in pixels relative to
262 the widget) and the last two elements give the width and height
263 of the character, in pixels. The bounding box may refer to a
264 region outside the visible area of the window.
265 pathName cget option
267 Returns the current value of the configuration option given by
268 option. Option may have any of the values accepted by the entry
269 command.
270 pathName configure ?option? ?value option value ...?
272 Query or modify the configuration options of the widget. If no
273 option is specified, returns a list describing all of the avail‐
274 able options for pathName (see Tk_ConfigureInfo for information
275 on the format of this list). If option is specified with no
276 value, then the command returns a list describing the one named
277 option (this list will be identical to the corresponding sublist
278 of the value returned if no option is specified). If one or
279 more option-value pairs are specified, then the command modifies
280 the given widget option(s) to have the given value(s); in this
281 case the command returns an empty string. Option may have any
282 of the values accepted by the entry command.
283 pathName delete first ?last?
285 Delete one or more elements of the entry. First is the index of
286 the first character to delete, and last is the index of the
287 character just after the last one to delete. If last is not
288 specified it defaults to first+1, i.e. a single character is
289 deleted. This command returns an empty string.
290 pathName get
292 Returns the entry's string.
293 pathName icursor index
295 Arrange for the insertion cursor to be displayed just before the
296 character given by index. Returns an empty string.
297 pathName index index
299 Returns the numerical index corresponding to index.
300 pathName insert index string
302 Insert the characters of string just before the character indi‐
303 cated by index. Returns an empty string.
304 pathName scan option args
306 This command is used to implement scanning on entries. It has
307 two forms, depending on option:
308 pathName scan mark x
310 Records x and the current view in the entry window; used
311 in conjunction with later scan dragto commands. Typi‐
312 cally this command is associated with a mouse button
313 press in the widget. It returns an empty string.
314 pathName scan dragto x
316 This command computes the difference between its x argu‐
317 ment and the x argument to the last scan mark command for
318 the widget. It then adjusts the view left or right by 10
319 times the difference in x-coordinates. This command is
320 typically associated with mouse motion events in the wid‐
321 get, to produce the effect of dragging the entry at high
322 speed through the window. The return value is an empty
323 string.
324 pathName selection option arg
326 This command is used to adjust the selection within an entry.
327 It has several forms, depending on option:
328 pathName selection adjust index
330 Locate the end of the selection nearest to the character
331 given by index, and adjust that end of the selection to
332 be at index (i.e. including but not going beyond index).
333 The other end of the selection is made the anchor point
334 for future select to commands. If the selection is not
335 currently in the entry, then a new selection is created
336 to include the characters between index and the most re‐
337 cent selection anchor point, inclusive. Returns an empty
338 string.
339 pathName selection clear
341 Clear the selection if it is currently in this widget.
342 If the selection is not in this widget then the command
343 has no effect. Returns an empty string.
344 pathName selection from index
346 Set the selection anchor point to just before the charac‐
347 ter given by index. Does not change the selection. Re‐
348 turns an empty string.
349 pathName selection present
351 Returns 1 if there is are characters selected in the en‐
352 try, 0 if nothing is selected.
353 pathName selection range start end
355 Sets the selection to include the characters starting
356 with the one indexed by start and ending with the one
357 just before end. If end refers to the same character as
358 start or an earlier one, then the entry's selection is
359 cleared.
360 pathName selection to index
362 If index is before the anchor point, set the selection to
363 the characters from index up to but not including the an‐
364 chor point. If index is the same as the anchor point, do
365 nothing. If index is after the anchor point, set the se‐
366 lection to the characters from the anchor point up to but
367 not including index. The anchor point is determined by
368 the most recent select from or select adjust command in
369 this widget. If the selection is not in this widget then
370 a new selection is created using the most recent anchor
371 point specified for the widget. Returns an empty string.
372 pathName validate
374 This command is used to force an evaluation of the -validatecom‐
375 mand independent of the conditions specified by the -validate
376 option. This is done by temporarily setting the -validate op‐
377 tion to all. It returns 0 or 1.
378 pathName xview args
380 This command is used to query and change the horizontal position
381 of the text in the widget's window. It can take any of the fol‐
382 lowing forms:
383 pathName xview
385 Returns a list containing two elements. Each element is
386 a real fraction between 0 and 1; together they describe
387 the horizontal span that is visible in the window. For
388 example, if the first element is .2 and the second ele‐
389 ment is .6, 20% of the entry's text is off-screen to the
390 left, the middle 40% is visible in the window, and 40% of
391 the text is off-screen to the right. These are the same
392 values passed to scrollbars via the -xscrollcommand op‐
393 tion.
394 pathName xview index
396 Adjusts the view in the window so that the character
397 given by index is displayed at the left edge of the win‐
398 dow.
399 pathName xview moveto fraction
401 Adjusts the view in the window so that the character
402 fraction of the way through the text appears at the left
403 edge of the window. Fraction must be a fraction between
404 0 and 1.
405 pathName xview scroll number what
407 This command shifts the view in the window left or right
408 according to number and what. Number must be an integer.
409 What must be either units or pages or an abbreviation of
410 one of these. If what is units, the view adjusts left or
411 right by number average-width characters on the display;
412 if it is pages then the view adjusts by number screen‐
413 fuls. If number is negative then characters farther to
414 the left become visible; if it is positive then charac‐
415 ters farther to the right become visible.
416
418 Tk automatically creates class bindings for entries that give them the
419 following default behavior. In the descriptions below, “word” refers to
420 a contiguous group of letters, digits, or “_” characters, or any single
421 character other than these.
422 [1] Clicking mouse button 1 positions the insertion cursor just be‐
424 fore the character underneath the mouse cursor, sets the input
425 focus to this widget, and clears any selection in the widget.
426 Dragging with mouse button 1 strokes out a selection between the
427 insertion cursor and the character under the mouse.
428 [2] Double-clicking with mouse button 1 selects the word under the
430 mouse and positions the insertion cursor at the end of the word.
431 Dragging after a double click will stroke out a selection con‐
432 sisting of whole words.
433 [3] Triple-clicking with mouse button 1 selects all of the text in
435 the entry and positions the insertion cursor at the end of the
436 line.
437 [4] The ends of the selection can be adjusted by dragging with mouse
439 button 1 while the Shift key is down; this will adjust the end
440 of the selection that was nearest to the mouse cursor when but‐
441 ton 1 was pressed. If the button is double-clicked before drag‐
442 ging then the selection will be adjusted in units of whole
443 words.
444 [5] Clicking mouse button 1 with the Control key down will position
446 the insertion cursor in the entry without affecting the selec‐
447 tion.
448 [6] If any normal printing characters are typed in an entry, they
450 are inserted at the point of the insertion cursor.
451 [7] The view in the entry can be adjusted by dragging with the mid‐
453 dle mouse button (button 2, or button 3 in TkAqua). If the mid‐
454 dle mouse button is clicked without moving the mouse, the selec‐
455 tion is copied into the entry at the position of the mouse cur‐
456 sor.
457 [8] If the mouse is dragged out of the entry on the left or right
459 sides while button 1 is pressed, the entry will automatically
460 scroll to make more text visible (if there is more text off-
461 screen on the side where the mouse left the window).
462 [9] The Left and Right keys move the insertion cursor one character
464 to the left or right; they also clear any selection in the en‐
465 try and set the selection anchor. If Left or Right is typed
466 with the Shift key down, then the insertion cursor moves and the
467 selection is extended to include the new character. Control-
468 Left and Control-Right move the insertion cursor by words, and
469 Control-Shift-Left and Control-Shift-Right move the insertion
470 cursor by words and also extend the selection. Control-b and
471 Control-f behave the same as Left and Right, respectively.
472 Meta-b and Meta-f behave the same as Control-Left and Control-
473 Right, respectively.
474 [10] The Home key, or Control-a, will move the insertion cursor to
476 the beginning of the entry and clear any selection in the entry.
477 Shift-Home moves the insertion cursor to the beginning of the
478 entry and also extends the selection to that point.
479 [11] The End key, or Control-e, will move the insertion cursor to the
481 end of the entry and clear any selection in the entry. Shift-
482 End moves the cursor to the end and extends the selection to
483 that point.
484 [12] The Select key and Control-Space set the selection anchor to the
486 position of the insertion cursor. They do not affect the cur‐
487 rent selection. Shift-Select and Control-Shift-Space adjust the
488 selection to the current position of the insertion cursor, se‐
489 lecting from the anchor to the insertion cursor if there was not
490 any selection previously.
491 [13] Control-/ selects all the text in the entry.
493 [14] Control-\ clears any selection in the entry.
495 [15] The F16 key (labelled Copy on many Sun workstations) or Meta-w
497 copies the selection in the widget to the clipboard, if there is
498 a selection.
499 [16] The F20 key (labelled Cut on many Sun workstations) or Control-w
501 copies the selection in the widget to the clipboard and deletes
502 the selection. If there is no selection in the widget then
503 these keys have no effect.
504 [17] The F18 key (labelled Paste on many Sun workstations) or Con‐
506 trol-y inserts the contents of the clipboard at the position of
507 the insertion cursor.
508 [18] The Delete key deletes the selection, if there is one in the en‐
510 try. If there is no selection, it deletes the character to the
511 right of the insertion cursor.
512 [19] The BackSpace key and Control-h delete the selection, if there
514 is one in the entry. If there is no selection, it deletes the
515 character to the left of the insertion cursor.
516 [20] Control-d deletes the character to the right of the insertion
518 cursor.
519 [21] Meta-d deletes the word to the right of the insertion cursor.
521 [22] Control-k deletes all the characters to the right of the inser‐
523 tion cursor.
524 [23] Control-t reverses the order of the two characters to the right
526 of the insertion cursor.
527 If the entry is disabled using the -state option, then the entry's view
529 can still be adjusted and text in the entry can still be selected, but
530 no insertion cursor will be displayed and no text modifications will
531 take place except if the entry is linked to a variable using the
532 -textvariable option, in which case any changes to the variable are re‐
533 flected by the entry whatever the value of its -state option.
534 The behavior of entries can be changed by defining new bindings for in‐
536 dividual widgets or by redefining the class bindings.
537
539 ttk::entry(n)
540
542 entry, widget
543Tk 8.3 entry(n)