1Entry(3)              User Contributed Perl Documentation             Entry(3)
2
3
4

NAME

6       Tk::Entry - Create and manipulate Entry widgets
7

SYNOPSIS

9           $entry = $parent->Entry(?options?);
10

STANDARD OPTIONS

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

WIDGET-SPECIFIC OPTIONS

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
27       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
34       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
43       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
50       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
61       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
74       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
82       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
94       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

DESCRIPTION

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
111       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
122       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

VALIDATION

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
136       none
137           Default.  This means no validation will occur.
138
139       focus
140           validateCommand will be called when the entry receives or loses
141           focus.
142
143       focusin
144           validateCommand will be called when the entry receives focus.
145
146       focusout
147           validateCommand will be called when the entry loses focus.
148
149       key validateCommand will be called when the entry is edited.
150
151       all validateCommand will be called for all above conditions.
152
153       The validateCommand and invalidCommand are called with the following
154       arguments:
155
156       ·   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
160       ·   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
164       ·   The current value of entry i.e. before the proposed change.
165
166       ·   index of char string to be added/deleted, if any. -1 otherwise
167
168       ·   type of action. 1 == INSERT, 0 == DELETE, -1 if it's a forced
169           validation or textvariable validation
170
171       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
177       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
182       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

WIDGET METHODS

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
195       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
199       number
200           Specifies the character as a numerical index, where 0 corresponds
201           to the first character in the string.
202
203       anchor
204           Indicates the anchor point for the selection, which is set with the
205           selectionFrom and selectionAdjust methods.
206
207       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
211       insert
212           Indicates the character adjacent to and immediately following the
213           insertion cursor.
214
215       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
219       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
224       @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
229       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
233       The following additional methods are available for entry widgets:
234
235       $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
244       $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
249       $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
262       $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
269       $entry->get
270           Returns the entry's string.
271
272       $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
276       $entry->index(index)
277           Returns the numerical index corresponding to index.
278
279       $entry->insert(index, string)
280           Insert the characters of string just before the character indicated
281           by index.  Returns an empty string.
282
283       $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
288           $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
294           $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
303       $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
308           $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
319           $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
324           $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
329           $entry->selectionPresent
330                   Returns 1 if there is are characters selected in the entry,
331                   0 if nothing is selected.
332
333           $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
339           $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
351       $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
356       $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
361           $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
371           $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
375           $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
381           $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

DEFAULT BINDINGS

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
398       [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
404       [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
409       [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
413       [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
419       [5] Clicking mouse button 1 with the Control key down will position the
420           insertion cursor in the entry without affecting the selection.
421
422       [6] If any normal printing characters are typed in an entry, they are
423           inserted at the point of the insertion cursor.
424
425       [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
430       [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
435       [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
446       [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
452       [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
458       [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
466       [13]
467           Control-/ selects all the text in the entry.
468
469       [14]
470           Control-\ clears any selection in the entry.
471
472       [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
477       [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
483       [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
488       [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
493       [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
498       [20]
499           Control-d deletes the character to the right of the insertion
500           cursor.
501
502       [21]
503           Meta-d deletes the word to the right of the insertion cursor.
504
505       [22]
506           Control-k deletes all the characters to the right of the insertion
507           cursor.
508
509       [23]
510           Control-t reverses the order of the two characters to the right of
511           the insertion cursor.
512
513           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
518           The behavior of entries can be changed by defining new bindings for
519           individual widgets or by redefining the class bindings.
520

KEYWORDS

522       entry, widget
523
524
525
526perl v5.12.0                      2010-05-13                          Entry(3)
Impressum