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