1entry(n)                     Tk Built-In Commands                     entry(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       entry - Create and manipulate entry widgets
9

SYNOPSIS

11       entry pathName ?options?
12

STANDARD OPTIONS

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
23       See the options manual entry for details on the standard options.
24

WIDGET-SPECIFIC OPTIONS

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
70

DESCRIPTION

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
80       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
91       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

VALIDATION

100       Validation  works  by  setting  the  validateCommand option to a script │
101       which will be evaluated according to the validate option as follows:    │
102
103       none                                                                    
104                 Default.  This means no validation will occur.                │
105
106       focus                                                                   
107                 validateCommand will be called when  the  entry  receives  or │
108                 loses focus.                                                  │
109
110       focusin                                                                 
111                 validateCommand will be called when the entry receives focus. │
112
113       focusout                                                                
114                 validateCommand will be called when the entry loses focus.    │
115
116       key                                                                     
117                 validateCommand will be called when the entry is edited.      │
118
119       all                                                                     
120                 validateCommand will be called for all above conditions.      │
121
122       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
126       %d                                                                      
127            Type  of  action:  1  for  insert,  0 for delete, or -1 for focus, │
128            forced or textvariable validation.                                 │
129
130       %i                                                                      
131            Index of char string to be inserted/deleted, if any, otherwise -1. │
132
133       %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
138       %s                                                                      
139            The current value of entry prior to editing.                       │
140
141       %S                                                                      
142            The text string being inserted/deleted, if any, {} otherwise.      │
143
144       %v                                                                      
145            The type of validation currently set.                              │
146
147       %V                                                                      
148            The type of validation that triggered the callback (key,  focusin, │
149            focusout, forced).                                                 │
150
151       %W                                                                      
152            The name of the entry widget.                                      │
153
154       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
163       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

WIDGET COMMAND

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
184       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
188       number      Specifies the character as a numerical index, where 0  cor‐
189                   responds to the first character in the string.
190
191       anchor      Indicates  the anchor point for the selection, which is set
192                   with the select from and select adjust widget commands.
193
194       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
198       insert      Indicates the character adjacent to and immediately follow‐
199                   ing the insertion cursor.
200
201       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
205       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
209       @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
214       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
218       The following commands are possible for entry widgets:
219
220       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
229       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
234       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
247       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
254       pathName get
255              Returns the entry's string.
256
257       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
261       pathName index index
262              Returns the numerical index corresponding to index.
263
264       pathName insert index string
265              Insert  the characters of string just before the character indi‐
266              cated by index.  Returns an empty string.
267
268       pathName scan option args
269              This command is used to implement scanning on entries.   It  has
270              two forms, depending on option:
271
272              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
278              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
288       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
292              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
303              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
308              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
313              pathName selection present
314                     Returns 1 if there is  are  characters  selected  in  the
315                     entry, 0 if nothing is selected.
316
317              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
324              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
337       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
343       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
348              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
359              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
364              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
370              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

DEFAULT BINDINGS

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
387       [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
393       [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
398       [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
402       [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
409       [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
413       [6]    If any normal printing characters are typed in  an  entry,  they
414              are inserted at the point of the insertion cursor.
415
416       [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
421       [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
426       [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
438       [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
443       [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
448       [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
455       [13]   Control-/ selects all the text in the entry.
456
457       [14]   Control-\ clears any selection in the entry.
458
459       [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
463       [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
468       [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
472       [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
476       [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
480       [20]   Control-d  deletes  the  character to the right of the insertion
481              cursor.
482
483       [21]   Meta-d deletes the word to the right of the insertion cursor.
484
485       [22]   Control-k deletes all the characters to the right of the  inser‐
486              tion cursor.
487
488       [23]   Control-t  reverses the order of the two characters to the right
489              of the insertion cursor.
490
491       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
498       The  behavior  of  entries  can be changed by defining new bindings for
499       individual widgets or by redefining the class bindings.
500
501

KEYWORDS

503       entry, widget
504
505
506
507Tk                                    8.3                             entry(n)
Impressum