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 -selectforeground
13 -borderwidth -highlightcolor -insertwidth -takefocus
14 -cursor -highlightthickness -justify -textvariable
15 -exportselection -insertbackground -relief -xscrollcommand
16 -font -insertborderwidth -selectbackground
17 -foreground -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
67 displayed, even if the input focus is in the widget; the contents
68 of 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
72 -disabledforeground 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
92 edition 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
108 command 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
113 typically bound to keystrokes and mouse actions. When first created,
114 an 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
117 protocols for handling the selection; entry selections are available
118 as 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
161 validation is due to focus, explcit call to validate or if change
162 is due to "-textvariable" changing.
163 · The current value of entry i.e. before the proposed change.
165 · index of char string to be added/deleted, if any. -1 otherwise
167 · type of action. 1 == INSERT, 0 == DELETE, -1 if it's a forced
169 validation or textvariable validation
170 In general, the textVariable and validateCommand can be dangerous to
172 mix. If you try set the textVariable to something that the
173 validateCommand will not accept it will be set back to the value of the
174 entry widget. Using the textVariable for read-only purposes will never
175 cause problems.
176 The validateCommand will turn itself off by setting validate to none
178 when an error occurs, for example when the validateCommand or
179 invalidCommand encounters an error in its script while evaluating, or
180 validateCommand does not return a valid boolean value.
181 With the perl/Tk version validate option is supposed to be "suspended"
183 while executing the validateCommand or the invalidCommand. This is
184 experimental but in theory either callback can "correct" the value of
185 the widget, and override the proposed change. (validateCommand should
186 still return false to inhibit the change from happening when it
187 returns.)
188
190 The Entry method creates a widget object. This object supports the
191 configure and cget methods described in Tk::options which can be used
192 to enquire and modify the options described above. The widget also
193 inherits all the methods provided by the generic Tk::Widget class.
194 Many of the additional methods for entries take one or more indices as
196 arguments. An index specifies a particular character in the entry's
197 string, in any of the following ways:
198 number
200 Specifies the character as a numerical index, where 0 corresponds
201 to the first character in the string.
202 anchor
204 Indicates the anchor point for the selection, which is set with the
205 selectionFrom and selectionAdjust methods.
206 end Indicates the character just after the last one in the entry's
208 string. This is equivalent to specifying a numerical index equal
209 to the length of the entry's string.
210 insert
212 Indicates the character adjacent to and immediately following the
213 insertion cursor.
214 sel.first
216 Indicates the first character in the selection. It is an error to
217 use this form if the selection isn't in the entry window.
218 sel.last
220 Indicates the character just after the last one in the selection.
221 It is an error to use this form if the selection isn't in the entry
222 window.
223 @number
225 In this form, number is treated as an x-coordinate in the entry's
226 window; the character spanning that x-coordinate is used. For
227 example, ``@0'' indicates the left-most character in the window.
228 Abbreviations may be used for any of the forms above, e.g. ``e'' or
230 ``sel.f''. In general, out-of-range indices are automatically rounded
231 to the nearest legal value.
232 The following additional methods are available for entry widgets:
234 $entry->bbox(index)
236 Returns a list of four numbers describing the bounding box of the
237 character given by index. The first two elements of the list give
238 the x and y coordinates of the upper-left corner of the screen area
239 covered by the character (in pixels relative to the widget) and the
240 last two elements give the width and height of the character, in
241 pixels. The bounding box may refer to a region outside the visible
242 area of the window.
243 $entry->cget(?option?)
245 Returns the current value of the configuration option given by
246 option. Option may have any of the values accepted by the entry
247 command.
248 $entry->configure(?option?, ?value, option, value, ...?)
250 Query or modify the configuration options of the widget. If no
251 option is specified, returns a list describing all of the available
252 options for $entry (see Tk::configure for information on the format
253 of this list). If option is specified with no value, then the
254 command returns a list describing the one named option (this list
255 will be identical to the corresponding sublist of the value
256 returned if no option is specified). If one or more option-value
257 pairs are specified, then the command modifies the given widget
258 option(s) to have the given value(s); in this case the command
259 returns an empty string. Option may have any of the values
260 accepted by the entry command.
261 $entry->delete(first, ?last?)
263 Delete one or more elements of the entry. First is the index of
264 the first character to delete, and last is the index of the
265 character just after the last one to delete. If last isn't
266 specified it defaults to first+1, i.e. a single character is
267 deleted. This method returns an empty string.
268 $entry->get
270 Returns the entry's string.
271 $entry->icursor(index)
273 Arrange for the insertion cursor to be displayed just before the
274 character given by index. Returns an empty string.
275 $entry->index(index)
277 Returns the numerical index corresponding to index.
278 $entry->insert(index, string)
280 Insert the characters of string just before the character indicated
281 by index. Returns an empty string.
282 $entry->scan(option, args)
284 $entry->scanOption(args)
285 This method is used to implement scanning on entries. It has two
286 forms, depending on Option:
287 $entry->scanMark(x)
289 Records x and the current view in the entry widget; used
290 in conjunction with later scanDragto methods. Typically
291 this method is associated with a mouse button press in the
292 widget. It returns an empty string.
293 $entry->scanDragto(x)
295 This method computes the difference between its x argument
296 and the x argument to the last scanMark method for the
297 widget. It then adjusts the view left or right by 10 times
298 the difference in x-coordinates. This method is typically
299 associated with mouse motion events in the widget, to
300 produce the effect of dragging the entry at high speed
301 through the widget. The return value is an empty string.
302 $entry->selection(option, arg)
304 $entry->selectionOption(arg)
305 This method is used to adjust the selection within an entry. It
306 has several forms, depending on Option:
307 $entry->selectionAdjust(index)
309 Locate the end of the selection nearest to the character
310 given by index, and adjust that end of the selection to be
311 at index (i.e including but not going beyond index). The
312 other end of the selection is made the anchor point for
313 future selectionTo methods. If the selection isn't
314 currently in the entry, then a new selection is created to
315 include the characters between index and the most recent
316 selection anchor point, inclusive. Returns an empty
317 string.
318 $entry->selectionClear
320 Clear the selection if it is currently in this widget. If
321 the selection isn't in this widget then the method has no
322 effect. Returns an empty string.
323 $entry->selectionFrom(index)
325 Set the selection anchor point to just before the character
326 given by index. Doesn't change the selection. Returns an
327 empty string.
328 $entry->selectionPresent
330 Returns 1 if there is are characters selected in the entry,
331 0 if nothing is selected.
332 $entry->selectionRange(start, end)
334 Sets the selection to include the characters starting with
335 the one indexed by start and ending with the one just
336 before end. If end refers to the same character as start
337 or an earlier one, then the entry's selection is cleared.
338 $entry->selectionTo(index)
340 If index is before the anchor point, set the selection to
341 the characters from index up to but not including the
342 anchor point. If index is the same as the anchor point, do
343 nothing. If index is after the anchor point, set the
344 selection to the characters from the anchor point up to but
345 not including index. The anchor point is determined by the
346 most recent selectionFrom or selectionAdjust method in this
347 widget. If the selection isn't in this widget then a new
348 selection is created using the most recent anchor point
349 specified for the widget. Returns an empty string.
350 $entry->validate
352 This command is used to force an evaluation of the validateCommand
353 independent of the conditions specified by the validate option. It
354 returns 0 or 1.
355 $entry->xview(args)
357 This command is used to query and change the horizontal position of
358 the text in the widget's window. It can take any of the following
359 forms:
360 $entry->xview
362 Returns a list containing two elements. Each element is a
363 real fraction between 0 and 1; together they describe the
364 horizontal span that is visible in the window. For
365 example, if the first element is .2 and the second element
366 is .7, 20% of the entry's text is off-screen to the left,
367 the middle 50% is visible in the window, and 30% of the
368 text is off-screen to the right. These are the same values
369 passed to scrollbars via the -xscrollcommand option.
370 $entry->xview(index)
372 Adjusts the view in the window so that the character given
373 by index is displayed at the left edge of the window.
374 $entry->xviewMoveto(fraction)
376 Adjusts the view in the window so that the character
377 fraction of the way through the text appears at the left
378 edge of the window. Fraction must be a fraction between 0
379 and 1.
380 $entry->xviewScroll(number, what)
382 This method shifts the view in the window left or right
383 according to number and what. Number must be an integer.
384 What must be either units or pages or an abbreviation of
385 one of these. If what is units, the view adjusts left or
386 right by number average-width characters on the display;
387 if it is pages then the view adjusts by number screenfuls.
388 If number is negative then characters farther to the left
389 become visible; if it is positive then characters farther
390 to the right become visible.
391
393 Tk automatically creates class bindings for entries that give them the
394 following default behavior. In the descriptions below, ``word'' refers
395 to a contiguous group of letters, digits, or ``_'' characters, or any
396 single character other than these.
397 [1] Clicking mouse button 1 positions the insertion cursor just before
399 the character underneath the mouse cursor, sets the input focus to
400 this widget, and clears any selection in the widget. Dragging with
401 mouse button 1 strokes out a selection between the insertion cursor
402 and the character under the mouse.
403 [2] Double-clicking with mouse button 1 selects the word under the
405 mouse and positions the insertion cursor at the beginning of the
406 word. Dragging after a double click will stroke out a selection
407 consisting of whole words.
408 [3] Triple-clicking with mouse button 1 selects all of the text in the
410 entry and positions the insertion cursor before the first
411 character.
412 [4] The ends of the selection can be adjusted by dragging with mouse
414 button 1 while the Shift key is down; this will adjust the end of
415 the selection that was nearest to the mouse cursor when button 1
416 was pressed. If the button is double-clicked before dragging then
417 the selection will be adjusted in units of whole words.
418 [5] Clicking mouse button 1 with the Control key down will position the
420 insertion cursor in the entry without affecting the selection.
421 [6] If any normal printing characters are typed in an entry, they are
423 inserted at the point of the insertion cursor.
424 [7] The view in the entry can be adjusted by dragging with mouse button
426 2. If mouse button 2 is clicked without moving the mouse, the
427 selection is copied into the entry at the position of the mouse
428 cursor.
429 [8] If the mouse is dragged out of the entry on the left or right sides
431 while button 1 is pressed, the entry will automatically scroll to
432 make more text visible (if there is more text off-screen on the
433 side where the mouse left the window).
434 [9] The Left and Right keys move the insertion cursor one character to
436 the left or right; they also clear any selection in the entry and
437 set the selection anchor. If Left or Right is typed with the Shift
438 key down, then the insertion cursor moves and the selection is
439 extended to include the new character. Control-Left and Control-
440 Right move the insertion cursor by words, and Control-Shift-Left
441 and Control-Shift-Right move the insertion cursor by words and also
442 extend the selection. Control-b and Control-f behave the same as
443 Left and Right, respectively. Meta-b and Meta-f behave the same as
444 Control-Left and Control-Right, respectively.
445 [10]
447 The Home key, or Control-a, will move the insertion cursor to the
448 beginning of the entry and clear any selection in the entry.
449 Shift-Home moves the insertion cursor to the beginning of the entry
450 and also extends the selection to that point.
451 [11]
453 The End key, or Control-e, will move the insertion cursor to the
454 end of the entry and clear any selection in the entry. Shift-End
455 moves the cursor to the end and extends the selection to that
456 point.
457 [12]
459 The Select key and Control-Space set the selection anchor to the
460 position of the insertion cursor. They don't affect the current
461 selection. Shift-Select and Control-Shift-Space adjust the
462 selection to the current position of the insertion cursor,
463 selecting from the anchor to the insertion cursor if there was not
464 any selection previously.
465 [13]
467 Control-/ selects all the text in the entry.
468 [14]
470 Control-\ clears any selection in the entry.
471 [15]
473 The F16 key (labelled Copy on many Sun workstations) or Meta-w
474 copies the selection in the widget to the clipboard, if there is a
475 selection.
476 [16]
478 The F20 key (labelled Cut on many Sun workstations) or Control-w
479 copies the selection in the widget to the clipboard and deletes the
480 selection. If there is no selection in the widget then these keys
481 have no effect.
482 [17]
484 The F18 key (labelled Paste on many Sun workstations) or Control-y
485 inserts the contents of the clipboard at the position of the
486 insertion cursor.
487 [18]
489 The Delete key deletes the selection, if there is one in the entry.
490 If there is no selection, it deletes the character to the right of
491 the insertion cursor.
492 [19]
494 The BackSpace key and Control-h delete the selection, if there is
495 one in the entry. If there is no selection, it deletes the
496 character to the left of the insertion cursor.
497 [20]
499 Control-d deletes the character to the right of the insertion
500 cursor.
501 [21]
503 Meta-d deletes the word to the right of the insertion cursor.
504 [22]
506 Control-k deletes all the characters to the right of the insertion
507 cursor.
508 [23]
510 Control-t reverses the order of the two characters to the right of
511 the insertion cursor.
512 If the entry is disabled using the -state option, then the entry's
514 view can still be adjusted and text in the entry can still be
515 selected, but no insertion cursor will be displayed and no text
516 modifications will take place.
517 The behavior of entries can be changed by defining new bindings for
519 individual widgets or by redefining the class bindings.
520
522 entry, widget
523perl v5.12.0 2010-05-13 Entry(3)