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,
91 focus, focusin, focusout, key, or all. It defaults to none.
92 When you want validation, you must explicitly state which mode
93 you 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
131 selected as described below. If an entry is exporting its selection
132 (see the -exportselection option), then it will observe the standard
133 X11 protocols for handling the selection; entry selections are avail‐
134 able as type STRING. Entries also observe the standard Tk rules for
135 dealing with the input focus. When an entry has the input focus it
136 displays an insertion cursor to indicate where new characters will be
137 inserted.
138 Entries are capable of displaying strings that are too long to fit
140 entirely within the widget's window. In this case, only a portion of
141 the string will be displayed; commands described below may be used to
142 change the view in the window. Entries use the standard -xscrollcom‐
143 mand mechanism for interacting with scrollbars (see the description of
144 the -xscrollcommand option for details). They also support scanning,
145 as described below.
146
148 Validation works by setting the -validatecommand option to a script
149 (validateCommand) which will be evaluated according to the -validate
150 option as follows:
151 none Default. This means no validation will occur.
153 focus validateCommand will be called when the entry receives or
155 loses focus.
156 focusin validateCommand will be called when the entry receives focus.
158 focusout validateCommand will be called when the entry loses focus.
160 key validateCommand will be called when the entry is edited.
162 all validateCommand will be called for all above conditions.
164 It is possible to perform percent substitutions on the value of the
166 -validatecommand and -invalidcommand options, just as you would in a
167 bind script. The following substitutions are recognized:
168 %d Type of action: 1 for insert, 0 for delete, or -1 for focus,
170 forced or textvariable validation.
171 %i Index of char string to be inserted/deleted, if any, otherwise -1.
173 %P The value of the entry if the edit is allowed. If you are config‐
175 uring the entry widget to have a new textvariable, this will be
176 the value of that textvariable.
177 %s The current value of entry prior to editing.
179 %S The text string being inserted/deleted, if any, {} otherwise.
181 %v The type of validation currently set.
183 %V The type of validation that triggered the callback (key, focusin,
185 focusout, forced).
186 %W The name of the entry widget.
188 In general, the -textvariable and -validatecommand options can be dan‐
190 gerous to mix. Any problems have been overcome so that using the -val‐
191 idatecommand will not interfere with the traditional behavior of the
192 entry widget. Using the -textvariable for read-only purposes will
193 never cause problems. The danger comes when you try set the -textvari‐
194 able to something that the -validatecommand would not accept, which
195 causes -validate to become none (the -invalidcommand will not be trig‐
196 gered). The same happens when an error occurs evaluating the -vali‐
197 datecommand.
198 Primarily, an error will occur when the -validatecommand or -invalid‐
200 command encounters an error in its script while evaluating or -vali‐
201 datecommand does not return a valid Tcl boolean value. The -validate
202 option will also set itself to none when you edit the entry widget from
203 within either the -validatecommand or the -invalidcommand. Such edi‐
204 tions will override the one that was being validated. If you wish to
205 edit the entry widget (for example set it to {}) during validation and
206 still have the -validate option set, you should include the command
207 after idle {%W config -validate %v}
208 in the -validatecommand or -invalidcommand (whichever one you were
209 editing the entry widget from). It is also recommended to not set an
210 associated -textvariable during validation, as that can cause the entry
211 widget to become out of sync with the -textvariable.
212
214 The entry command creates a new Tcl command whose name is pathName.
215 This command may be used to invoke various operations on the widget.
216 It has the following general form:
217 pathName subcommand ?arg arg ...?
218 Subcommand and the args determine the exact behavior of the command.
219 INDICES
221 Many of the widget commands for entries take one or more indices as
222 arguments. An index specifies a particular character in the entry's
223 string, in any of the following ways:
224 number Specifies the character as a numerical index, where 0 cor‐
226 responds to the first character in the string.
227 anchor Indicates the anchor point for the selection, which is set
229 with the select from and select adjust widget commands.
230 end Indicates the character just after the last one in the
232 entry's string. This is equivalent to specifying a numeri‐
233 cal index equal to the length of the entry's string.
234 insert Indicates the character adjacent to and immediately follow‐
236 ing the insertion cursor.
237 sel.first Indicates the first character in the selection. It is an
239 error to use this form if the selection is not in the entry
240 window.
241 sel.last Indicates the character just after the last one in the
243 selection. It is an error to use this form if the selec‐
244 tion is not in the entry window.
245 @number In this form, number is treated as an x-coordinate in the
247 entry's window; the character spanning that x-coordinate
248 is used. For example, “@0” indicates the left-most charac‐
249 ter in the window.
250 Abbreviations may be used for any of the forms above, e.g. “e” or
252 “sel.f”. In general, out-of-range indices are automatically rounded to
253 the nearest legal value.
254 SUBCOMMANDS
256 The following commands are possible for entry widgets:
257 pathName bbox index
259 Returns a list of four numbers describing the bounding box of
260 the character given by index. The first two elements of the
261 list give the x and y coordinates of the upper-left corner of
262 the screen area covered by the character (in pixels relative to
263 the widget) and the last two elements give the width and height
264 of the character, in pixels. The bounding box may refer to a
265 region outside the visible area of the window.
266 pathName cget option
268 Returns the current value of the configuration option given by
269 option. Option may have any of the values accepted by the entry
270 command.
271 pathName configure ?option? ?value option value ...?
273 Query or modify the configuration options of the widget. If no
274 option is specified, returns a list describing all of the avail‐
275 able options for pathName (see Tk_ConfigureInfo for information
276 on the format of this list). If option is specified with no
277 value, then the command returns a list describing the one named
278 option (this list will be identical to the corresponding sublist
279 of the value returned if no option is specified). If one or
280 more option-value pairs are specified, then the command modifies
281 the given widget option(s) to have the given value(s); in this
282 case the command returns an empty string. Option may have any
283 of the values accepted by the entry command.
284 pathName delete first ?last?
286 Delete one or more elements of the entry. First is the index of
287 the first character to delete, and last is the index of the
288 character just after the last one to delete. If last is not
289 specified it defaults to first+1, i.e. a single character is
290 deleted. This command returns an empty string.
291 pathName get
293 Returns the entry's string.
294 pathName icursor index
296 Arrange for the insertion cursor to be displayed just before the
297 character given by index. Returns an empty string.
298 pathName index index
300 Returns the numerical index corresponding to index.
301 pathName insert index string
303 Insert the characters of string just before the character indi‐
304 cated by index. Returns an empty string.
305 pathName scan option args
307 This command is used to implement scanning on entries. It has
308 two forms, depending on option:
309 pathName scan mark x
311 Records x and the current view in the entry window; used
312 in conjunction with later scan dragto commands. Typi‐
313 cally this command is associated with a mouse button
314 press in the widget. It returns an empty string.
315 pathName scan dragto x
317 This command computes the difference between its x argu‐
318 ment and the x argument to the last scan mark command for
319 the widget. It then adjusts the view left or right by 10
320 times the difference in x-coordinates. This command is
321 typically associated with mouse motion events in the wid‐
322 get, to produce the effect of dragging the entry at high
323 speed through the window. The return value is an empty
324 string.
325 pathName selection option arg
327 This command is used to adjust the selection within an entry.
328 It has several forms, depending on option:
329 pathName selection adjust index
331 Locate the end of the selection nearest to the character
332 given by index, and adjust that end of the selection to
333 be at index (i.e. including but not going beyond index).
334 The other end of the selection is made the anchor point
335 for future select to commands. If the selection is not
336 currently in the entry, then a new selection is created
337 to include the characters between index and the most
338 recent selection anchor point, inclusive. Returns an
339 empty string.
340 pathName selection clear
342 Clear the selection if it is currently in this widget.
343 If the selection is not in this widget then the command
344 has no effect. Returns an empty string.
345 pathName selection from index
347 Set the selection anchor point to just before the charac‐
348 ter given by index. Does not change the selection.
349 Returns an empty string.
350 pathName selection present
352 Returns 1 if there is are characters selected in the
353 entry, 0 if nothing is selected.
354 pathName selection range start end
356 Sets the selection to include the characters starting
357 with the one indexed by start and ending with the one
358 just before end. If end refers to the same character as
359 start or an earlier one, then the entry's selection is
360 cleared.
361 pathName selection to index
363 If index is before the anchor point, set the selection to
364 the characters from index up to but not including the
365 anchor point. If index is the same as the anchor point,
366 do nothing. If index is after the anchor point, set the
367 selection to the characters from the anchor point up to
368 but not including index. The anchor point is determined
369 by the most recent select from or select adjust command
370 in this widget. If the selection is not in this widget
371 then a new selection is created using the most recent
372 anchor point specified for the widget. Returns an empty
373 string.
374 pathName validate
376 This command is used to force an evaluation of the -validatecom‐
377 mand independent of the conditions specified by the -validate
378 option. This is done by temporarily setting the -validate
379 option to all. It returns 0 or 1.
380 pathName xview args
382 This command is used to query and change the horizontal position
383 of the text in the widget's window. It can take any of the fol‐
384 lowing forms:
385 pathName xview
387 Returns a list containing two elements. Each element is
388 a real fraction between 0 and 1; together they describe
389 the horizontal span that is visible in the window. For
390 example, if the first element is .2 and the second ele‐
391 ment is .6, 20% of the entry's text is off-screen to the
392 left, the middle 40% is visible in the window, and 40% of
393 the text is off-screen to the right. These are the same
394 values passed to scrollbars via the -xscrollcommand
395 option.
396 pathName xview index
398 Adjusts the view in the window so that the character
399 given by index is displayed at the left edge of the win‐
400 dow.
401 pathName xview moveto fraction
403 Adjusts the view in the window so that the character
404 fraction of the way through the text appears at the left
405 edge of the window. Fraction must be a fraction between
406 0 and 1.
407 pathName xview scroll number what
409 This command shifts the view in the window left or right
410 according to number and what. Number must be an integer.
411 What must be either units or pages or an abbreviation of
412 one of these. If what is units, the view adjusts left or
413 right by number average-width characters on the display;
414 if it is pages then the view adjusts by number screen‐
415 fuls. If number is negative then characters farther to
416 the left become visible; if it is positive then charac‐
417 ters farther to the right become visible.
418
420 Tk automatically creates class bindings for entries that give them the
421 following default behavior. In the descriptions below, “word” refers to
422 a contiguous group of letters, digits, or “_” characters, or any single
423 character other than these.
424 [1] Clicking mouse button 1 positions the insertion cursor just
426 before the character underneath the mouse cursor, sets the input
427 focus to this widget, and clears any selection in the widget.
428 Dragging with mouse button 1 strokes out a selection between the
429 insertion cursor and the character under the mouse.
430 [2] Double-clicking with mouse button 1 selects the word under the
432 mouse and positions the insertion cursor at the end of the word.
433 Dragging after a double click will stroke out a selection con‐
434 sisting of whole words.
435 [3] Triple-clicking with mouse button 1 selects all of the text in
437 the entry and positions the insertion cursor at the end of the
438 line.
439 [4] The ends of the selection can be adjusted by dragging with mouse
441 button 1 while the Shift key is down; this will adjust the end
442 of the selection that was nearest to the mouse cursor when but‐
443 ton 1 was pressed. If the button is double-clicked before drag‐
444 ging then the selection will be adjusted in units of whole
445 words.
446 [5] Clicking mouse button 1 with the Control key down will position
448 the insertion cursor in the entry without affecting the selec‐
449 tion.
450 [6] If any normal printing characters are typed in an entry, they
452 are inserted at the point of the insertion cursor.
453 [7] The view in the entry can be adjusted by dragging with mouse
455 button 2. If mouse button 2 is clicked without moving the
456 mouse, the selection is copied into the entry at the position of
457 the mouse cursor.
458 [8] If the mouse is dragged out of the entry on the left or right
460 sides while button 1 is pressed, the entry will automatically
461 scroll to make more text visible (if there is more text off-
462 screen on the side where the mouse left the window).
463 [9] The Left and Right keys move the insertion cursor one character
465 to the left or right; they also clear any selection in the
466 entry and set the selection anchor. If Left or Right is typed
467 with the Shift key down, then the insertion cursor moves and the
468 selection is extended to include the new character. Control-
469 Left and Control-Right move the insertion cursor by words, and
470 Control-Shift-Left and Control-Shift-Right move the insertion
471 cursor by words and also extend the selection. Control-b and
472 Control-f behave the same as Left and Right, respectively.
473 Meta-b and Meta-f behave the same as Control-Left and Control-
474 Right, respectively.
475 [10] The Home key, or Control-a, will move the insertion cursor to
477 the beginning of the entry and clear any selection in the entry.
478 Shift-Home moves the insertion cursor to the beginning of the
479 entry and also extends the selection to that point.
480 [11] The End key, or Control-e, will move the insertion cursor to the
482 end of the entry and clear any selection in the entry. Shift-
483 End moves the cursor to the end and extends the selection to
484 that point.
485 [12] The Select key and Control-Space set the selection anchor to the
487 position of the insertion cursor. They do not affect the cur‐
488 rent selection. Shift-Select and Control-Shift-Space adjust the
489 selection to the current position of the insertion cursor,
490 selecting from the anchor to the insertion cursor if there was
491 not any selection previously.
492 [13] Control-/ selects all the text in the entry.
494 [14] Control-\ clears any selection in the entry.
496 [15] The F16 key (labelled Copy on many Sun workstations) or Meta-w
498 copies the selection in the widget to the clipboard, if there is
499 a selection.
500 [16] The F20 key (labelled Cut on many Sun workstations) or Control-w
502 copies the selection in the widget to the clipboard and deletes
503 the selection. If there is no selection in the widget then
504 these keys have no effect.
505 [17] The F18 key (labelled Paste on many Sun workstations) or Con‐
507 trol-y inserts the contents of the clipboard at the position of
508 the insertion cursor.
509 [18] The Delete key deletes the selection, if there is one in the
511 entry. If there is no selection, it deletes the character to
512 the right of the insertion cursor.
513 [19] The BackSpace key and Control-h delete the selection, if there
515 is one in the entry. If there is no selection, it deletes the
516 character to the left of the insertion cursor.
517 [20] Control-d deletes the character to the right of the insertion
519 cursor.
520 [21] Meta-d deletes the word to the right of the insertion cursor.
522 [22] Control-k deletes all the characters to the right of the inser‐
524 tion cursor.
525 [23] Control-t reverses the order of the two characters to the right
527 of the insertion cursor.
528 If the entry is disabled using the -state option, then the entry's view
530 can still be adjusted and text in the entry can still be selected, but
531 no insertion cursor will be displayed and no text modifications will
532 take place except if the entry is linked to a variable using the
533 -textvariable option, in which case any changes to the variable are
534 reflected by the entry whatever the value of its -state option.
535 The behavior of entries can be changed by defining new bindings for
537 individual widgets or by redefining the class bindings.
538
540 ttk::entry(n)
541
543 entry, widget
544Tk 8.3 entry(n)