1entry(n) Tk Built-In Commands entry(n)
2______________________________________________________________________________
6
8 entry - Create and manipulate 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 [-disabledbackground disabledBackground] Specifies the background color
27 to use when the entry is disabled. If this option is the empty string,
28 the normal background color is used. [-disabledforeground disabled‐
29 Foreground] Specifies the foreground color to use when the entry is
30 disabled. If this option is the empty string, the normal foreground
31 color is used. [-invalidcommand or -invcmd invalidCommand] Specifies a
32 script to eval when validateCommand returns 0. Setting it to {} dis‐
33 ables this feature (the default). The best use of this option is to
34 set it to bell. See Validation below for more information. [-read‐
35 onlybackground readonlyBackground] Specifies the background color to
36 use when the entry is readonly. If this option is the empty string,
37 the normal background color is used. [-show show] If this option is
38 specified, then the true contents of the entry are not displayed in the
39 window. Instead, each character in the entry's value will be displayed
40 as the first character in the value of this option, such as “*”. This
41 is useful, for example, if the entry is to be used to enter a password.
42 If characters in the entry are selected and copied elsewhere, the
43 information copied will be what is displayed, not the true contents of
44 the entry. [-state state] Specifies one of three states for the entry:
45 normal, disabled, or readonly. If the entry is readonly, then the
46 value may not be changed using widget commands and no insertion cursor
47 will be displayed, even if the input focus is in the widget; the con‐
48 tents of the widget may still be selected. If the entry is disabled,
49 the value may not be changed, no insertion cursor will be displayed,
50 the contents will not be selectable, and the entry may be displayed in
51 a different color, depending on the values of the -disabledforeground
52 and -disabledbackground options. [-validate validate] Specifies the
53 mode in which validation should operate: none, focus, focusin, focu‐
54 sout, key, or all. It defaults to none. When you want validation, you
55 must explicitly state which mode you wish to use. See Validation below
56 for more. [-validatecommand or -vcmd validateCommand] Specifies a
57 script to eval when you want to validate the input into the entry wid‐
58 get. Setting it to {} disables this feature (the default). This com‐
59 mand must return a valid Tcl boolean value. If it returns 0 (or the
60 valid Tcl boolean equivalent) then it means you reject the new edition
61 and it will not occur and the invalidCommand will be evaluated if it is
62 set. If it returns 1, then the new edition occurs. See Validation
63 below for more information. [-width width] Specifies an integer value
64 indicating the desired width of the entry window, in average-size char‐
65 acters of the widget's font. If the value is less than or equal to
66 zero, the widget picks a size just large enough to hold its current
67 text.
68_________________________________________________________________
69
71 The entry command creates a new window (given by the pathName argument)
72 and makes it into an entry widget. Additional options, described
73 above, may be specified on the command line or in the option database
74 to configure aspects of the entry such as its colors, font, and relief.
75 The entry command returns its pathName argument. At the time this com‐
76 mand is invoked, there must not exist a window named pathName, but
77 pathName's parent must exist.
78 An entry is a widget that displays a one-line text string and allows
80 that string to be edited using widget commands described below, which
81 are typically bound to keystrokes and mouse actions. When first cre‐
82 ated, an entry's string is empty. A portion of the entry may be
83 selected as described below. If an entry is exporting its selection
84 (see the exportSelection option), then it will observe the standard X11
85 protocols for handling the selection; entry selections are available
86 as type STRING. Entries also observe the standard Tk rules for dealing
87 with the input focus. When an entry has the input focus it displays an
88 insertion cursor to indicate where new characters will be inserted.
89 Entries are capable of displaying strings that are too long to fit
91 entirely within the widget's window. In this case, only a portion of
92 the string will be displayed; commands described below may be used to
93 change the view in the window. Entries use the standard xScrollCommand
94 mechanism for interacting with scrollbars (see the description of the
95 xScrollCommand option for details). They also support scanning, as
96 described below.
97
99 Validation works by setting the validateCommand option to a script
100 which will be evaluated according to the validate option as follows:
101 none Default. This means no validation will occur.
103 focus validateCommand will be called when the entry receives or
105 loses focus.
106 focusin validateCommand will be called when the entry receives focus.
108 focusout validateCommand will be called when the entry loses focus.
110 key validateCommand will be called when the entry is edited.
112 all validateCommand will be called for all above conditions.
114 It is possible to perform percent substitutions on the validateCommand
116 and invalidCommand, just as you would in a bind script. The following
117 substitutions are recognized:
118 %d Type of action: 1 for insert, 0 for delete, or -1 for focus,
120 forced or textvariable validation.
121 %i Index of char string to be inserted/deleted, if any, otherwise -1.
123 %P The value of the entry if the edit is allowed. If you are config‐
125 uring the entry widget to have a new textvariable, this will be
126 the value of that textvariable.
127 %s The current value of entry prior to editing.
129 %S The text string being inserted/deleted, if any, {} otherwise.
131 %v The type of validation currently set.
133 %V The type of validation that triggered the callback (key, focusin,
135 focusout, forced).
136 %W The name of the entry widget.
138 In general, the textVariable and validateCommand can be dangerous to
140 mix. Any problems have been overcome so that using the validateCommand
141 will not interfere with the traditional behavior of the entry widget.
142 Using the textVariable for read-only purposes will never cause prob‐
143 lems. The danger comes when you try set the textVariable to something
144 that the validateCommand would not accept, which causes validate to
145 become none (the invalidCommand will not be triggered). The same hap‐
146 pens when an error occurs evaluating the validateCommand.
147 Primarily, an error will occur when the validateCommand or invalidCom‐
149 mand encounters an error in its script while evaluating or validateCom‐
150 mand does not return a valid Tcl boolean value. The validate option
151 will also set itself to none when you edit the entry widget from within
152 either the validateCommand or the invalidCommand. Such editions will
153 override the one that was being validated. If you wish to edit the
154 entry widget (for example set it to {}) during validation and still
155 have the validate option set, you should include the command
156 after idle {%W config -validate %v}
157 in the validateCommand or invalidCommand (whichever one you were edit‐
158 ing the entry widget from). It is also recommended to not set an asso‐
159 ciated textVariable during validation, as that can cause the entry wid‐
160 get to become out of sync with the textVariable.
161
163 The entry command creates a new Tcl command whose name is pathName.
164 This command may be used to invoke various operations on the widget.
165 It has the following general form:
166 pathName subcommand ?arg arg ...?
167 Subcommand and the args determine the exact behavior of the command.
168 INDICES
170 Many of the widget commands for entries take one or more indices as
171 arguments. An index specifies a particular character in the entry's
172 string, in any of the following ways:
173 number Specifies the character as a numerical index, where 0 cor‐
175 responds to the first character in the string.
176 anchor Indicates the anchor point for the selection, which is set
178 with the select from and select adjust widget commands.
179 end Indicates the character just after the last one in the
181 entry's string. This is equivalent to specifying a numeri‐
182 cal index equal to the length of the entry's string.
183 insert Indicates the character adjacent to and immediately follow‐
185 ing the insertion cursor.
186 sel.first Indicates the first character in the selection. It is an
188 error to use this form if the selection is not in the entry
189 window.
190 sel.last Indicates the character just after the last one in the
192 selection. It is an error to use this form if the selec‐
193 tion is not in the entry window.
194 @number In this form, number is treated as an x-coordinate in the
196 entry's window; the character spanning that x-coordinate
197 is used. For example, “@0” indicates the left-most charac‐
198 ter in the window.
199 Abbreviations may be used for any of the forms above, e.g. “e” or
201 “sel.f”. In general, out-of-range indices are automatically rounded to
202 the nearest legal value.
203 SUBCOMMANDS
205 The following commands are possible for entry widgets:
206 pathName bbox index
208 Returns a list of four numbers describing the bounding box of
209 the character given by index. The first two elements of the
210 list give the x and y coordinates of the upper-left corner of
211 the screen area covered by the character (in pixels relative to
212 the widget) and the last two elements give the width and height
213 of the character, in pixels. The bounding box may refer to a
214 region outside the visible area of the window.
215 pathName cget option
217 Returns the current value of the configuration option given by
218 option. Option may have any of the values accepted by the entry
219 command.
220 pathName configure ?option? ?value option value ...?
222 Query or modify the configuration options of the widget. If no
223 option is specified, returns a list describing all of the avail‐
224 able options for pathName (see Tk_ConfigureInfo for information
225 on the format of this list). If option is specified with no
226 value, then the command returns a list describing the one named
227 option (this list will be identical to the corresponding sublist
228 of the value returned if no option is specified). If one or
229 more option-value pairs are specified, then the command modifies
230 the given widget option(s) to have the given value(s); in this
231 case the command returns an empty string. Option may have any
232 of the values accepted by the entry command.
233 pathName delete first ?last?
235 Delete one or more elements of the entry. First is the index of
236 the first character to delete, and last is the index of the
237 character just after the last one to delete. If last is not
238 specified it defaults to first+1, i.e. a single character is
239 deleted. This command returns an empty string.
240 pathName get
242 Returns the entry's string.
243 pathName icursor index
245 Arrange for the insertion cursor to be displayed just before the
246 character given by index. Returns an empty string.
247 pathName index index
249 Returns the numerical index corresponding to index.
250 pathName insert index string
252 Insert the characters of string just before the character indi‐
253 cated by index. Returns an empty string.
254 pathName scan option args
256 This command is used to implement scanning on entries. It has
257 two forms, depending on option:
258 pathName scan mark x
260 Records x and the current view in the entry window; used
261 in conjunction with later scan dragto commands. Typi‐
262 cally this command is associated with a mouse button
263 press in the widget. It returns an empty string.
264 pathName scan dragto x
266 This command computes the difference between its x argu‐
267 ment and the x argument to the last scan mark command for
268 the widget. It then adjusts the view left or right by 10
269 times the difference in x-coordinates. This command is
270 typically associated with mouse motion events in the wid‐
271 get, to produce the effect of dragging the entry at high
272 speed through the window. The return value is an empty
273 string.
274 pathName selection option arg
276 This command is used to adjust the selection within an entry.
277 It has several forms, depending on option:
278 pathName selection adjust index
280 Locate the end of the selection nearest to the character
281 given by index, and adjust that end of the selection to
282 be at index (i.e. including but not going beyond index).
283 The other end of the selection is made the anchor point
284 for future select to commands. If the selection is not
285 currently in the entry, then a new selection is created
286 to include the characters between index and the most
287 recent selection anchor point, inclusive. Returns an
288 empty string.
289 pathName selection clear
291 Clear the selection if it is currently in this widget.
292 If the selection is not in this widget then the command
293 has no effect. Returns an empty string.
294 pathName selection from index
296 Set the selection anchor point to just before the charac‐
297 ter given by index. Does not change the selection.
298 Returns an empty string.
299 pathName selection present
301 Returns 1 if there is are characters selected in the
302 entry, 0 if nothing is selected.
303 pathName selection range start end
305 Sets the selection to include the characters starting
306 with the one indexed by start and ending with the one
307 just before end. If end refers to the same character as
308 start or an earlier one, then the entry's selection is
309 cleared.
310 pathName selection to index
312 If index is before the anchor point, set the selection to
313 the characters from index up to but not including the
314 anchor point. If index is the same as the anchor point,
315 do nothing. If index is after the anchor point, set the
316 selection to the characters from the anchor point up to
317 but not including index. The anchor point is determined
318 by the most recent select from or select adjust command
319 in this widget. If the selection is not in this widget
320 then a new selection is created using the most recent
321 anchor point specified for the widget. Returns an empty
322 string.
323 pathName validate
325 This command is used to force an evaluation of the validateCom‐
326 mand independent of the conditions specified by the validate
327 option. This is done by temporarily setting the validate option
328 to all. It returns 0 or 1.
329 pathName xview args
331 This command is used to query and change the horizontal position
332 of the text in the widget's window. It can take any of the fol‐
333 lowing forms:
334 pathName xview
336 Returns a list containing two elements. Each element is
337 a real fraction between 0 and 1; together they describe
338 the horizontal span that is visible in the window. For
339 example, if the first element is .2 and the second ele‐
340 ment is .6, 20% of the entry's text is off-screen to the
341 left, the middle 40% is visible in the window, and 40% of
342 the text is off-screen to the right. These are the same
343 values passed to scrollbars via the -xscrollcommand
344 option.
345 pathName xview index
347 Adjusts the view in the window so that the character
348 given by index is displayed at the left edge of the win‐
349 dow.
350 pathName xview moveto fraction
352 Adjusts the view in the window so that the character
353 fraction of the way through the text appears at the left
354 edge of the window. Fraction must be a fraction between
355 0 and 1.
356 pathName xview scroll number what
358 This command shifts the view in the window left or right
359 according to number and what. Number must be an integer.
360 What must be either units or pages or an abbreviation of
361 one of these. If what is units, the view adjusts left or
362 right by number average-width characters on the display;
363 if it is pages then the view adjusts by number screen‐
364 fuls. If number is negative then characters farther to
365 the left become visible; if it is positive then charac‐
366 ters farther to the right become visible.
367
369 Tk automatically creates class bindings for entries that give them the
370 following default behavior. In the descriptions below, “word” refers to
371 a contiguous group of letters, digits, or “_” characters, or any single
372 character other than these.
373 [1] Clicking mouse button 1 positions the insertion cursor just
375 before the character underneath the mouse cursor, sets the input
376 focus to this widget, and clears any selection in the widget.
377 Dragging with mouse button 1 strokes out a selection between the
378 insertion cursor and the character under the mouse.
379 [2] Double-clicking with mouse button 1 selects the word under the
381 mouse and positions the insertion cursor at the end of the word.
382 Dragging after a double click will stroke out a selection con‐
383 sisting of whole words.
384 [3] Triple-clicking with mouse button 1 selects all of the text in
386 the entry and positions the insertion cursor at the end of the
387 line.
388 [4] The ends of the selection can be adjusted by dragging with mouse
390 button 1 while the Shift key is down; this will adjust the end
391 of the selection that was nearest to the mouse cursor when but‐
392 ton 1 was pressed. If the button is double-clicked before drag‐
393 ging then the selection will be adjusted in units of whole
394 words.
395 [5] Clicking mouse button 1 with the Control key down will position
397 the insertion cursor in the entry without affecting the selec‐
398 tion.
399 [6] If any normal printing characters are typed in an entry, they
401 are inserted at the point of the insertion cursor.
402 [7] The view in the entry can be adjusted by dragging with mouse
404 button 2. If mouse button 2 is clicked without moving the
405 mouse, the selection is copied into the entry at the position of
406 the mouse cursor.
407 [8] If the mouse is dragged out of the entry on the left or right
409 sides while button 1 is pressed, the entry will automatically
410 scroll to make more text visible (if there is more text off-
411 screen on the side where the mouse left the window).
412 [9] The Left and Right keys move the insertion cursor one character
414 to the left or right; they also clear any selection in the
415 entry and set the selection anchor. If Left or Right is typed
416 with the Shift key down, then the insertion cursor moves and the
417 selection is extended to include the new character. Control-
418 Left and Control-Right move the insertion cursor by words, and
419 Control-Shift-Left and Control-Shift-Right move the insertion
420 cursor by words and also extend the selection. Control-b and
421 Control-f behave the same as Left and Right, respectively.
422 Meta-b and Meta-f behave the same as Control-Left and Control-
423 Right, respectively.
424 [10] The Home key, or Control-a, will move the insertion cursor to
426 the beginning of the entry and clear any selection in the entry.
427 Shift-Home moves the insertion cursor to the beginning of the
428 entry and also extends the selection to that point.
429 [11] The End key, or Control-e, will move the insertion cursor to the
431 end of the entry and clear any selection in the entry. Shift-
432 End moves the cursor to the end and extends the selection to
433 that point.
434 [12] The Select key and Control-Space set the selection anchor to the
436 position of the insertion cursor. They do not affect the cur‐
437 rent selection. Shift-Select and Control-Shift-Space adjust the
438 selection to the current position of the insertion cursor,
439 selecting from the anchor to the insertion cursor if there was
440 not any selection previously.
441 [13] Control-/ selects all the text in the entry.
443 [14] Control-\ clears any selection in the entry.
445 [15] The F16 key (labelled Copy on many Sun workstations) or Meta-w
447 copies the selection in the widget to the clipboard, if there is
448 a selection.
449 [16] The F20 key (labelled Cut on many Sun workstations) or Control-w
451 copies the selection in the widget to the clipboard and deletes
452 the selection. If there is no selection in the widget then
453 these keys have no effect.
454 [17] The F18 key (labelled Paste on many Sun workstations) or Con‐
456 trol-y inserts the contents of the clipboard at the position of
457 the insertion cursor.
458 [18] The Delete key deletes the selection, if there is one in the
460 entry. If there is no selection, it deletes the character to
461 the right of the insertion cursor.
462 [19] The BackSpace key and Control-h delete the selection, if there
464 is one in the entry. If there is no selection, it deletes the
465 character to the left of the insertion cursor.
466 [20] Control-d deletes the character to the right of the insertion
468 cursor.
469 [21] Meta-d deletes the word to the right of the insertion cursor.
471 [22] Control-k deletes all the characters to the right of the inser‐
473 tion cursor.
474 [23] Control-t reverses the order of the two characters to the right
476 of the insertion cursor.
477 If the entry is disabled using the -state option, then the entry's view
479 can still be adjusted and text in the entry can still be selected, but
480 no insertion cursor will be displayed and no text modifications will
481 take place except if the entry is linked to a variable using the
482 -textvariable option, in which case any changes to the variable are
483 reflected by the entry whatever the value of its -state option.
484 The behavior of entries can be changed by defining new bindings for
486 individual widgets or by redefining the class bindings.
487
489 ttk::entry(n)
490
492 entry, widget
493Tk 8.3 entry(n)