1Entry(3) User Contributed Perl Documentation Entry(3)
2
6 Tk::Entry - Create and manipulate Entry widgets
7
9 $entry = $parent->Entry(?options?);
10
12 -background -highlightbackground -insertontime -selectfore‐
13 ground -borderwidth -highlightcolor -insertwidth -takefocus
14 -cursor -highlightthickness -justify -textvariable -exportselec‐
15 tion -insertbackground -relief -xscrollcommand
16 -font -insertborderwidth -selectbackground -fore‐
17 ground -insertofftime -selectborderwidth
18
20 Command-Line Name: -disabledbackground
21 Database Name: disabledBackground
22 Database Class: DisabledBackground
23 Specifies the background color to use when the entry is disabled.
24 If this option is the empty string, the normal background color is
25 used.
26 Command-Line Name: -disabledforeground
28 Database Name: disabledForeground
29 Database Class: DisabledForeground
30 Specifies the foreground color to use when the entry is disabled.
31 If this option is the empty string, the normal foreground color is
32 used.
33 Name: invalidCommand
35 Class: InvalidCommand
36 Switch: -invalidcommand
37 Alias: -invcmd
38 Specifies a script to eval when validateCommand returns 0. Setting
39 it to <undef> disables this feature (the default). The best use of
40 this option is to set it to bell. See Validation below for more
41 information.
42 Command-Line Name: -readonlybackground
44 Database Name: readonlyBackground
45 Database Class: ReadonlyBackground
46 Specifies the background color to use when the entry is read-only.
47 If this option is the empty string, the normal background color is
48 used.
49 Name: show
51 Class: Show
52 Switch: -show
53 If this option is specified, then the true contents of the entry
54 are not displayed in the window. Instead, each character in the
55 entry's value will be displayed as the first character in the value
56 of this option, such as ``*''. This is useful, for example, if the
57 entry is to be used to enter a password. If characters in the
58 entry are selected and copied elsewhere, the information copied
59 will be what is displayed, not the true contents of the entry.
60 Name: state
62 Class: State
63 Switch: -state
64 Specifies one of three states for the entry: normal, disabled, or
65 readonly. If the entry is readonly, then the value may not be
66 changed using widget commands and no insertion cursor will be dis‐
67 played, even if the input focus is in the widget; the contents of
68 the widget may still be selected. If the entry is disabled, the
69 value may not be changed, no insertion cursor will be displayed,
70 the contents will not be selectable, and the entry may be displayed
71 in a different color, depending on the values of the -disabledfore‐
72 ground and -disabledbackground options.
73 Name: validate
75 Class: Validate
76 Switch: -validate
77 Specifies the mode in which validation should operate: none, focus,
78 focusin, focusout, key, or all. It defaults to none. When you
79 want validation, you must explicitly state which mode you wish to
80 use. See Validation below for more.
81 Name: validateCommand
83 Class: ValidateCommand
84 Switch: -validatecommand
85 Alias: -vcmd
86 Specifies a script to eval when you want to validate the input into
87 the entry widget. Setting it to "undef" disables this feature (the
88 default). This command must return a valid boolean value. If it
89 returns 0 (or the valid boolean equivalent) then it means you
90 reject the new edition and it will not occur and the invalidCommand
91 will be evaluated if it is set. If it returns 1, then the new edi‐
92 tion occurs. See Validation below for more information.
93 Name: width
95 Class: Width
96 Switch: -width
97 Specifies an integer value indicating the desired width of the
98 entry window, in average-size characters of the widget's font. If
99 the value is less than or equal to zero, the widget picks a size
100 just large enough to hold its current text.
101
103 The Entry method creates a new window (given by the $entry argument)
104 and makes it into an entry widget. Additional options, described
105 above, may be specified on the command line or in the option database
106 to configure aspects of the entry such as its colors, font, and relief.
107 The entry command returns its $entry argument. At the time this com‐
108 mand is invoked, there must not exist a window named $entry, but
109 $entry's parent must exist.
110 An entry is a widget that displays a one-line text string and allows
112 that string to be edited using methods described below, which are typi‐
113 cally bound to keystrokes and mouse actions. When first created, an
114 entry's string is empty. A portion of the entry may be selected as
115 described below. If an entry is exporting its selection (see the
116 exportSelection option), then it will observe the standard X11 proto‐
117 cols for handling the selection; entry selections are available as
118 type STRING. Entries also observe the standard Tk rules for dealing
119 with the input focus. When an entry has the input focus it displays an
120 insertion cursor to indicate where new characters will be inserted.
121 Entries are capable of displaying strings that are too long to fit
123 entirely within the widget's window. In this case, only a portion of
124 the string will be displayed; methods described below may be used to
125 change the view in the window. Entries use the standard xScrollCommand
126 mechanism for interacting with scrollbars (see the description of the
127 -xscrollcommand option for details). They also support scanning, as
128 described below.
129
131 Validation of entry widgets is derived from part of the patch written
132 by jhobbs@cs.uoregon.edu. This works by setting the validateCommand
133 option to a callback which will be evaluated according to the validate
134 option as follows:
135 none
137 Default. This means no validation will occur.
138 focus
140 validateCommand will be called when the entry receives or loses
141 focus.
142 focusin
144 validateCommand will be called when the entry receives focus.
145 focusout
147 validateCommand will be called when the entry loses focus.
148 key validateCommand will be called when the entry is edited.
150 all validateCommand will be called for all above conditions.
152 The validateCommand and invalidCommand are called with the following
154 arguments:
155 * The proposed value of the entry. If you are configuring the entry
157 widget to have a new textvariable, this will be the value of that
158 textvariable.
159 * The characters to be added (or deleted). This will be "undef" if val‐
160 idation is due to focus, explcit call to validate or if change is due
161 to "-textvariable" changing.
162 * The current value of entry i.e. before the proposed change.
163 * index of char string to be added/deleted, if any. -1 otherwise
164 * type of action. 1 == INSERT, 0 == DELETE, -1 if it's a forced valida‐
165 tion or textvariable validation
166 In general, the textVariable and validateCommand can be dangerous to
168 mix. If you try set the textVariable to something that the validateCom‐
169 mand will not accept it will be set back to the value of the entry wid‐
170 get. Using the textVariable for read-only purposes will never cause
171 problems.
172 The validateCommand will turn itself off by setting validate to none
174 when an error occurs, for example when the validateCommand or invalid‐
175 Command encounters an error in its script while evaluating, or vali‐
176 dateCommand does not return a valid boolean value.
177 With the perl/Tk version validate option is supposed to be "suspended"
179 while executing the validateCommand or the invalidCommand. This is
180 experimental but in theory either callback can "correct" the value of
181 the widget, and override the proposed change. (validateCommand should
182 still return false to inhibit the change from happening when it
183 returns.)
184
186 The Entry method creates a widget object. This object supports the
187 configure and cget methods described in Tk::options which can be used
188 to enquire and modify the options described above. The widget also
189 inherits all the methods provided by the generic Tk::Widget class.
190 Many of the additional methods for entries take one or more indices as
192 arguments. An index specifies a particular character in the entry's
193 string, in any of the following ways:
194 number
196 Specifies the character as a numerical index, where 0 corresponds
197 to the first character in the string.
198 anchor
200 Indicates the anchor point for the selection, which is set with the
201 selectionFrom and selectionAdjust methods.
202 end Indicates the character just after the last one in the entry's
204 string. This is equivalent to specifying a numerical index equal
205 to the length of the entry's string.
206 insert
208 Indicates the character adjacent to and immediately following the
209 insertion cursor.
210 sel.first
212 Indicates the first character in the selection. It is an error to
213 use this form if the selection isn't in the entry window.
214 sel.last
216 Indicates the character just after the last one in the selection.
217 It is an error to use this form if the selection isn't in the entry
218 window.
219 @number
221 In this form, number is treated as an x-coordinate in the entry's
222 window; the character spanning that x-coordinate is used. For
223 example, ``@0'' indicates the left-most character in the window.
224 Abbreviations may be used for any of the forms above, e.g. ``e'' or
226 ``sel.f''. In general, out-of-range indices are automatically rounded
227 to the nearest legal value.
228 The following additional methods are available for entry widgets:
230 $entry->bbox(index)
232 Returns a list of four numbers describing the bounding box of the
233 character given by index. The first two elements of the list give
234 the x and y coordinates of the upper-left corner of the screen area
235 covered by the character (in pixels relative to the widget) and the
236 last two elements give the width and height of the character, in
237 pixels. The bounding box may refer to a region outside the visible
238 area of the window.
239 $entry->delete(first, ?last?)
241 Returns the current value of the configuration option given by
242 option. Option may have any of the values accepted by the entry
243 command.
244 $entry->configure(?option?, ?value, option, value, ...?)
246 Query or modify the configuration options of the widget. If no
247 option is specified, returns a list describing all of the available
248 options for $entry (see Tk::configure for information on the format
249 of this list). If option is specified with no value, then the com‐
250 mand returns a list describing the one named option (this list will
251 be identical to the corresponding sublist of the value returned if
252 no option is specified). If one or more option-value pairs are
253 specified, then the command modifies the given widget option(s) to
254 have the given value(s); in this case the command returns an empty
255 string. Option may have any of the values accepted by the entry
256 command.
257 $entry->delete(first, ?last?)
259 Delete one or more elements of the entry. First is the index of
260 the first character to delete, and last is the index of the charac‐
261 ter just after the last one to delete. If last isn't specified it
262 defaults to first+1, i.e. a single character is deleted. This
263 method returns an empty string.
264 $entry->get
266 Returns the entry's string.
267 $entry->icursor(index)
269 Arrange for the insertion cursor to be displayed just before the
270 character given by index. Returns an empty string.
271 $entry->index(index)
273 Returns the numerical index corresponding to index.
274 $entry->insert(index, string)
276 Insert the characters of string just before the character indicated
277 by index. Returns an empty string.
278 $entry->scan(option, args)
280 $entry->scanOption(args)
281 This method is used to implement scanning on entries. It has two
282 forms, depending on Option:
283 $entry->scanMark(x)
285 Records x and the current view in the entry widget; used
286 in conjunction with later scanDragto methods. Typically
287 this method is associated with a mouse button press in the
288 widget. It returns an empty string.
289 $entry->scanDragto(x)
291 This method computes the difference between its x argument
292 and the x argument to the last scanMark method for the wid‐
293 get. It then adjusts the view left or right by 10 times
294 the difference in x-coordinates. This method is typically
295 associated with mouse motion events in the widget, to pro‐
296 duce the effect of dragging the entry at high speed through
297 the widget. The return value is an empty string.
298 $entry->selection(option, arg)
300 $entry->selectionOption(arg)
301 This method is used to adjust the selection within an entry. It
302 has several forms, depending on Option:
303 $entry->selectionAdjust(index)
305 Locate the end of the selection nearest to the character
306 given by index, and adjust that end of the selection to be
307 at index (i.e including but not going beyond index). The
308 other end of the selection is made the anchor point for
309 future selectionTo methods. If the selection isn't cur‐
310 rently in the entry, then a new selection is created to
311 include the characters between index and the most recent
312 selection anchor point, inclusive. Returns an empty
313 string.
314 $entry->selectionClear
316 Clear the selection if it is currently in this widget. If
317 the selection isn't in this widget then the method has no
318 effect. Returns an empty string.
319 $entry->selectionFrom(index)
321 Set the selection anchor point to just before the character
322 given by index. Doesn't change the selection. Returns an
323 empty string.
324 $entry->selectionPresent
326 Returns 1 if there is are characters selected in the entry,
327 0 if nothing is selected.
328 $entry->selectionRange(start, end)
330 Sets the selection to include the characters starting with
331 the one indexed by start and ending with the one just
332 before end. If end refers to the same character as start
333 or an earlier one, then the entry's selection is cleared.
334 $entry->selectionTo(index)
336 If index is before the anchor point, set the selection to
337 the characters from index up to but not including the
338 anchor point. If index is the same as the anchor point, do
339 nothing. If index is after the anchor point, set the
340 selection to the characters from the anchor point up to but
341 not including index. The anchor point is determined by the
342 most recent selectionFrom or selectionAdjust method in this
343 widget. If the selection isn't in this widget then a new
344 selection is created using the most recent anchor point
345 specified for the widget. Returns an empty string.
346 $entry->validate
348 This command is used to force an evaluation of the validateCommand
349 independent of the conditions specified by the validate option. It
350 returns 0 or 1.
351 $entry->xview(args)
353 This command is used to query and change the horizontal position of
354 the text in the widget's window. It can take any of the following
355 forms:
356 $entry->xview
358 Returns a list containing two elements. Each element is a
359 real fraction between 0 and 1; together they describe the
360 horizontal span that is visible in the window. For exam‐
361 ple, if the first element is .2 and the second element is
362 .7, 20% of the entry's text is off-screen to the left, the
363 middle 50% is visible in the window, and 30% of the text is
364 off-screen to the right. These are the same values passed
365 to scrollbars via the -xscrollcommand option.
366 $entry->xview(index)
368 Adjusts the view in the window so that the character given
369 by index is displayed at the left edge of the window.
370 $entry->xviewMoveto(fraction)
372 Adjusts the view in the window so that the character frac‐
373 tion of the way through the text appears at the left edge
374 of the window. Fraction must be a fraction between 0 and
375 1.
376 $entry->xviewScroll(number, what)
378 This method shifts the view in the window left or right
379 according to number and what. Number must be an integer.
380 What must be either units or pages or an abbreviation of
381 one of these. If what is units, the view adjusts left or
382 right by number average-width characters on the display;
383 if it is pages then the view adjusts by number screenfuls.
384 If number is negative then characters farther to the left
385 become visible; if it is positive then characters farther
386 to the right become visible.
387
389 Tk automatically creates class bindings for entries that give them the
390 following default behavior. In the descriptions below, ``word'' refers
391 to a contiguous group of letters, digits, or ``_'' characters, or any
392 single character other than these.
393 [1] Clicking mouse button 1 positions the insertion cursor just before
395 the character underneath the mouse cursor, sets the input focus to
396 this widget, and clears any selection in the widget. Dragging with
397 mouse button 1 strokes out a selection between the insertion cursor
398 and the character under the mouse.
399 [2] Double-clicking with mouse button 1 selects the word under the
401 mouse and positions the insertion cursor at the beginning of the
402 word. Dragging after a double click will stroke out a selection
403 consisting of whole words.
404 [3] Triple-clicking with mouse button 1 selects all of the text in the
406 entry and positions the insertion cursor before the first charac‐
407 ter.
408 [4] The ends of the selection can be adjusted by dragging with mouse
410 button 1 while the Shift key is down; this will adjust the end of
411 the selection that was nearest to the mouse cursor when button 1
412 was pressed. If the button is double-clicked before dragging then
413 the selection will be adjusted in units of whole words.
414 [5] Clicking mouse button 1 with the Control key down will position the
416 insertion cursor in the entry without affecting the selection.
417 [6] If any normal printing characters are typed in an entry, they are
419 inserted at the point of the insertion cursor.
420 [7] The view in the entry can be adjusted by dragging with mouse button
422 2. If mouse button 2 is clicked without moving the mouse, the
423 selection is copied into the entry at the position of the mouse
424 cursor.
425 [8] If the mouse is dragged out of the entry on the left or right sides
427 while button 1 is pressed, the entry will automatically scroll to
428 make more text visible (if there is more text off-screen on the
429 side where the mouse left the window).
430 [9] The Left and Right keys move the insertion cursor one character to
432 the left or right; they also clear any selection in the entry and
433 set the selection anchor. If Left or Right is typed with the Shift
434 key down, then the insertion cursor moves and the selection is
435 extended to include the new character. Control-Left and Control-
436 Right move the insertion cursor by words, and Control-Shift-Left
437 and Control-Shift-Right move the insertion cursor by words and also
438 extend the selection. Control-b and Control-f behave the same as
439 Left and Right, respectively. Meta-b and Meta-f behave the same as
440 Control-Left and Control-Right, respectively.
441 [10]
443 The Home key, or Control-a, will move the insertion cursor to the
444 beginning of the entry and clear any selection in the entry.
445 Shift-Home moves the insertion cursor to the beginning of the entry
446 and also extends the selection to that point.
447 [11]
449 The End key, or Control-e, will move the insertion cursor to the
450 end of the entry and clear any selection in the entry. Shift-End
451 moves the cursor to the end and extends the selection to that
452 point.
453 [12]
455 The Select key and Control-Space set the selection anchor to the
456 position of the insertion cursor. They don't affect the current
457 selection. Shift-Select and Control-Shift-Space adjust the selec‐
458 tion to the current position of the insertion cursor, selecting
459 from the anchor to the insertion cursor if there was not any selec‐
460 tion previously.
461 [13]
463 Control-/ selects all the text in the entry.
464 [14]
466 Control-\ clears any selection in the entry.
467 [15]
469 The F16 key (labelled Copy on many Sun workstations) or Meta-w
470 copies the selection in the widget to the clipboard, if there is a
471 selection.
472 [16]
474 The F20 key (labelled Cut on many Sun workstations) or Control-w
475 copies the selection in the widget to the clipboard and deletes the
476 selection. If there is no selection in the widget then these keys
477 have no effect.
478 [17]
480 The F18 key (labelled Paste on many Sun workstations) or Control-y
481 inserts the contents of the clipboard at the position of the inser‐
482 tion cursor.
483 [18]
485 The Delete key deletes the selection, if there is one in the entry.
486 If there is no selection, it deletes the character to the right of
487 the insertion cursor.
488 [19]
490 The BackSpace key and Control-h delete the selection, if there is
491 one in the entry. If there is no selection, it deletes the charac‐
492 ter to the left of the insertion cursor.
493 [20]
495 Control-d deletes the character to the right of the insertion cur‐
496 sor.
497 [21]
499 Meta-d deletes the word to the right of the insertion cursor.
500 [22]
502 Control-k deletes all the characters to the right of the insertion
503 cursor.
504 [23]
506 Control-t reverses the order of the two characters to the right of
507 the insertion cursor.
508 If the entry is disabled using the -state option, then the entry's
510 view can still be adjusted and text in the entry can still be
511 selected, but no insertion cursor will be displayed and no text
512 modifications will take place.
513 The behavior of entries can be changed by defining new bindings for
515 individual widgets or by redefining the class bindings.
516
518 entry, widget
519perl v5.8.8 2008-02-05 Entry(3)