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

NAME

8       entry - Create and manipulate 'entry' one-line text 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       Command-Line Name:-disabledbackground
27       Database Name:  disabledBackground
28       Database Class: DisabledBackground
29
30              Specifies  the  background  color  to use when the entry is dis‐
31              abled.  If this option is the empty  string,  the  normal  back‐
32              ground color is used.
33
34       Command-Line Name:-disabledforeground
35       Database Name:  disabledForeground
36       Database Class: DisabledForeground
37
38              Specifies  the  foreground  color  to use when the entry is dis‐
39              abled.  If this option is the empty  string,  the  normal  fore‐
40              ground color is used.
41
42       Command-Line Name:-invalidcommand or -invcmd
43       Database Name:  invalidCommand
44       Database Class: InvalidCommand
45
46              Specifies  a  script  to  eval  when -validatecommand returns 0.
47              Setting it to {} disables this feature (the default).  The  best
48              use  of  this option is to set it to bell.  See VALIDATION below
49              for more information.
50
51       Command-Line Name:-readonlybackground
52       Database Name:  readonlyBackground
53       Database Class: ReadonlyBackground
54
55              Specifies the background color to use when the  entry  is  read‐
56              only.  If this option is the empty string, the normal background
57              color is used.
58
59       Command-Line Name:-show
60       Database Name:  show
61       Database Class: Show
62
63              If this option is specified, then the true contents of the entry
64              are not displayed in the window.  Instead, each character in the
65              entry's value will be displayed as the first  character  in  the
66              value of this option, such as “*”.  This is useful, for example,
67              if the entry is to be used to enter a password.   If  characters
68              in  the entry are selected and copied elsewhere, the information
69              copied will be what is displayed, not the true contents  of  the
70              entry.
71
72       Command-Line Name:-state
73       Database Name:  state
74       Database Class: State
75
76              Specifies  one of three states for the entry:  normal, disabled,
77              or readonly.  If the entry is readonly, then the value  may  not
78              be changed using widget commands and no insertion cursor will be
79              displayed, even if the input focus is in the  widget;  the  con‐
80              tents of the widget may still be selected.  If the entry is dis‐
81              abled, the value may not be changed, no insertion cursor will be
82              displayed,  the  contents  will not be selectable, and the entry
83              may be displayed in a different color, depending on  the  values
84              of the -disabledforeground and -disabledbackground options.
85
86       Command-Line Name:-validate
87       Database Name:  validate
88       Database Class: Validate
89
90              Specifies  the  mode  in  which validation should operate: none,
91              focus, focusin, focusout, key, or all.   It  defaults  to  none.
92              When  you  want validation, you must explicitly state which mode
93              you wish to use.  See VALIDATION below for more.
94
95       Command-Line Name:-validatecommand or -vcmd
96       Database Name:  validateCommand
97       Database Class: ValidateCommand
98
99              Specifies a script to eval when you want to validate  the  input
100              into  the  entry widget.  Setting it to {} disables this feature
101              (the default).  This command must return  a  valid  Tcl  boolean
102              value.   If  it  returns 0 (or the valid Tcl boolean equivalent)
103              then it means you reject the new edition and it will  not  occur
104              and  the  -invalidcommand  will be evaluated if it is set. If it
105              returns 1, then the new edition occurs.   See  VALIDATION  below
106              for more information.
107
108       Command-Line Name:-width
109       Database Name:  width
110       Database Class: Width
111
112              Specifies  an  integer value indicating the desired width of the
113              entry window, in average-size characters of the  widget's  font.
114              If  the  value is less than or equal to zero, the widget picks a
115              size just large enough to hold its current text.
116______________________________________________________________________________
117

DESCRIPTION

119       The entry command creates a new window (given by the pathName argument)
120       and  makes  it  into  an  entry  widget.  Additional options, described
121       above, may be specified on the command line or in the  option  database
122       to configure aspects of the entry such as its colors, font, and relief.
123       The entry command returns its pathName argument.  At the time this com‐
124       mand  is  invoked,  there  must  not exist a window named pathName, but
125       pathName's parent must exist.
126
127       An entry is a widget that displays a one-line text  string  and  allows
128       that  string  to be edited using widget commands described below, which
129       are typically bound to keystrokes and mouse actions.  When  first  cre‐
130       ated,  an  entry's  string  is  empty.   A  portion of the entry may be
131       selected as described below.  If an entry is  exporting  its  selection
132       (see  the  -exportselection  option), then it will observe the standard
133       X11 protocols for handling the selection;  entry selections are  avail‐
134       able  as  type  STRING.  Entries also observe the standard Tk rules for
135       dealing with the input focus.  When an entry has  the  input  focus  it
136       displays  an  insertion cursor to indicate where new characters will be
137       inserted.
138
139       Entries are capable of displaying strings that  are  too  long  to  fit
140       entirely  within  the widget's window.  In this case, only a portion of
141       the string will be displayed;  commands described below may be used  to
142       change  the  view in the window.  Entries use the standard -xscrollcom‐
143       mand mechanism for interacting with scrollbars (see the description  of
144       the  -xscrollcommand  option for details).  They also support scanning,
145       as described below.
146

VALIDATION

148       Validation works by setting the -validatecommand  option  to  a  script
149       (validateCommand)  which  will  be evaluated according to the -validate
150       option as follows:
151
152       none      Default.  This means no validation will occur.
153
154       focus     validateCommand will be called when  the  entry  receives  or
155                 loses focus.
156
157       focusin   validateCommand will be called when the entry receives focus.
158
159       focusout  validateCommand will be called when the entry loses focus.
160
161       key       validateCommand will be called when the entry is edited.
162
163       all       validateCommand will be called for all above conditions.
164
165       It  is  possible  to  perform percent substitutions on the value of the
166       -validatecommand and -invalidcommand options, just as you  would  in  a
167       bind script.  The following substitutions are recognized:
168
169       %d   Type  of  action:  1  for  insert,  0 for delete, or -1 for focus,
170            forced or textvariable validation.
171
172       %i   Index of char string to be inserted/deleted, if any, otherwise -1.
173
174       %P   The value of the entry if the edit is allowed.  If you are config‐
175            uring  the  entry  widget to have a new textvariable, this will be
176            the value of that textvariable.
177
178       %s   The current value of entry prior to editing.
179
180       %S   The text string being inserted/deleted, if any, {} otherwise.
181
182       %v   The type of validation currently set.
183
184       %V   The type of validation that triggered the callback (key,  focusin,
185            focusout, forced).
186
187       %W   The name of the entry widget.
188
189       In  general, the -textvariable and -validatecommand options can be dan‐
190       gerous to mix.  Any problems have been overcome so that using the -val‐
191       idatecommand  will  not  interfere with the traditional behavior of the
192       entry widget.  Using the  -textvariable  for  read-only  purposes  will
193       never cause problems.  The danger comes when you try set the -textvari‐
194       able to something that the -validatecommand  would  not  accept,  which
195       causes  -validate to become none (the -invalidcommand will not be trig‐
196       gered).  The same happens when an error occurs  evaluating  the  -vali‐
197       datecommand.
198
199       Primarily,  an  error will occur when the -validatecommand or -invalid‐
200       command encounters an error in its script while  evaluating  or  -vali‐
201       datecommand  does  not return a valid Tcl boolean value.  The -validate
202       option will also set itself to none when you edit the entry widget from
203       within  either  the -validatecommand or the -invalidcommand.  Such edi‐
204       tions will override the one that was being validated.  If you  wish  to
205       edit  the entry widget (for example set it to {}) during validation and
206       still have the -validate option set, you should include the command
207              after idle {%W config -validate %v}
208       in the -validatecommand or  -invalidcommand  (whichever  one  you  were
209       editing  the  entry widget from).  It is also recommended to not set an
210       associated -textvariable during validation, as that can cause the entry
211       widget to become out of sync with the -textvariable.
212

WIDGET COMMAND

214       The  entry  command  creates  a new Tcl command whose name is pathName.
215       This command may be used to invoke various operations  on  the  widget.
216       It has the following general form:
217              pathName subcommand ?arg arg ...?
218       Subcommand and the args determine the exact behavior of the command.
219
220   INDICES
221       Many  of  the  widget  commands for entries take one or more indices as
222       arguments.  An index specifies a particular character  in  the  entry's
223       string, in any of the following ways:
224
225       number      Specifies  the character as a numerical index, where 0 cor‐
226                   responds to the first character in the string.
227
228       anchor      Indicates the anchor point for the selection, which is  set
229                   with the select from and select adjust widget commands.
230
231       end         Indicates  the  character  just  after  the last one in the
232                   entry's string.  This is equivalent to specifying a numeri‐
233                   cal index equal to the length of the entry's string.
234
235       insert      Indicates the character adjacent to and immediately follow‐
236                   ing the insertion cursor.
237
238       sel.first   Indicates the first character in the selection.  It  is  an
239                   error to use this form if the selection is not in the entry
240                   window.
241
242       sel.last    Indicates the character just after  the  last  one  in  the
243                   selection.   It  is an error to use this form if the selec‐
244                   tion is not in the entry window.
245
246       @number     In this form, number is treated as an x-coordinate  in  the
247                   entry's  window;   the character spanning that x-coordinate
248                   is used.  For example, “@0” indicates the left-most charac‐
249                   ter in the window.
250
251       Abbreviations  may  be  used  for  any of the forms above, e.g.  “e” or
252sel.f”.  In general, out-of-range indices are automatically rounded to
253       the nearest legal value.
254
255   SUBCOMMANDS
256       The following commands are possible for entry widgets:
257
258       pathName bbox index
259              Returns  a  list  of four numbers describing the bounding box of
260              the character given by index.  The first  two  elements  of  the
261              list  give  the  x and y coordinates of the upper-left corner of
262              the screen area covered by the character (in pixels relative  to
263              the  widget) and the last two elements give the width and height
264              of the character, in pixels.  The bounding box may  refer  to  a
265              region outside the visible area of the window.
266
267       pathName cget option
268              Returns  the  current value of the configuration option given by
269              option.  Option may have any of the values accepted by the entry
270              command.
271
272       pathName configure ?option? ?value option value ...?
273              Query  or modify the configuration options of the widget.  If no
274              option is specified, returns a list describing all of the avail‐
275              able  options for pathName (see Tk_ConfigureInfo for information
276              on the format of this list).  If option  is  specified  with  no
277              value,  then the command returns a list describing the one named
278              option (this list will be identical to the corresponding sublist
279              of  the  value  returned  if no option is specified).  If one or
280              more option-value pairs are specified, then the command modifies
281              the  given widget option(s) to have the given value(s);  in this
282              case the command returns an empty string.  Option may  have  any
283              of the values accepted by the entry command.
284
285       pathName delete first ?last?
286              Delete one or more elements of the entry.  First is the index of
287              the first character to delete, and last  is  the  index  of  the
288              character  just  after  the  last one to delete.  If last is not
289              specified it defaults to first+1, i.e.  a  single  character  is
290              deleted.  This command returns an empty string.
291
292       pathName get
293              Returns the entry's string.
294
295       pathName icursor index
296              Arrange for the insertion cursor to be displayed just before the
297              character given by index.  Returns an empty string.
298
299       pathName index index
300              Returns the numerical index corresponding to index.
301
302       pathName insert index string
303              Insert the characters of string just before the character  indi‐
304              cated by index.  Returns an empty string.
305
306       pathName scan option args
307              This  command  is used to implement scanning on entries.  It has
308              two forms, depending on option:
309
310              pathName scan mark x
311                     Records x and the current view in the entry window;  used
312                     in  conjunction  with  later scan dragto commands.  Typi‐
313                     cally this command is  associated  with  a  mouse  button
314                     press in the widget.  It returns an empty string.
315
316              pathName scan dragto x
317                     This  command computes the difference between its x argu‐
318                     ment and the x argument to the last scan mark command for
319                     the widget.  It then adjusts the view left or right by 10
320                     times the difference in x-coordinates.  This  command  is
321                     typically associated with mouse motion events in the wid‐
322                     get, to produce the effect of dragging the entry at  high
323                     speed  through  the window.  The return value is an empty
324                     string.
325
326       pathName selection option arg
327              This command is used to adjust the selection  within  an  entry.
328              It has several forms, depending on option:
329
330              pathName selection adjust index
331                     Locate  the end of the selection nearest to the character
332                     given by index, and adjust that end of the  selection  to
333                     be  at index (i.e. including but not going beyond index).
334                     The other end of the selection is made the  anchor  point
335                     for  future  select to commands.  If the selection is not
336                     currently in the entry, then a new selection  is  created
337                     to  include  the  characters  between  index and the most
338                     recent selection anchor  point,  inclusive.   Returns  an
339                     empty string.
340
341              pathName selection clear
342                     Clear  the  selection  if it is currently in this widget.
343                     If the selection is not in this widget then  the  command
344                     has no effect.  Returns an empty string.
345
346              pathName selection from index
347                     Set the selection anchor point to just before the charac‐
348                     ter given by  index.   Does  not  change  the  selection.
349                     Returns an empty string.
350
351              pathName selection present
352                     Returns  1  if  there  is  are characters selected in the
353                     entry, 0 if nothing is selected.
354
355              pathName selection range start end
356                     Sets the selection to  include  the  characters  starting
357                     with  the  one  indexed  by start and ending with the one
358                     just before end.  If end refers to the same character  as
359                     start  or  an  earlier one, then the entry's selection is
360                     cleared.
361
362              pathName selection to index
363                     If index is before the anchor point, set the selection to
364                     the  characters  from  index  up to but not including the
365                     anchor point.  If index is the same as the anchor  point,
366                     do  nothing.  If index is after the anchor point, set the
367                     selection to the characters from the anchor point  up  to
368                     but  not including index.  The anchor point is determined
369                     by the most recent select from or select  adjust  command
370                     in  this  widget.  If the selection is not in this widget
371                     then a new selection is created  using  the  most  recent
372                     anchor  point specified for the widget.  Returns an empty
373                     string.
374
375       pathName validate
376              This command is used to force an evaluation of the -validatecom‐
377              mand  independent  of  the conditions specified by the -validate
378              option.  This is  done  by  temporarily  setting  the  -validate
379              option to all.  It returns 0 or 1.
380
381       pathName xview args
382              This command is used to query and change the horizontal position
383              of the text in the widget's window.  It can take any of the fol‐
384              lowing forms:
385
386              pathName xview
387                     Returns  a list containing two elements.  Each element is
388                     a real fraction between 0 and 1;  together they  describe
389                     the  horizontal  span that is visible in the window.  For
390                     example, if the first element is .2 and the  second  ele‐
391                     ment  is .6, 20% of the entry's text is off-screen to the
392                     left, the middle 40% is visible in the window, and 40% of
393                     the  text is off-screen to the right.  These are the same
394                     values  passed  to  scrollbars  via  the  -xscrollcommand
395                     option.
396
397              pathName xview index
398                     Adjusts  the  view  in  the  window so that the character
399                     given by index is displayed at the left edge of the  win‐
400                     dow.
401
402              pathName xview moveto fraction
403                     Adjusts  the  view  in  the  window so that the character
404                     fraction of the way through the text appears at the  left
405                     edge  of the window.  Fraction must be a fraction between
406                     0 and 1.
407
408              pathName xview scroll number what
409                     This command shifts the view in the window left or  right
410                     according to number and what.  Number must be an integer.
411                     What must be either units or pages or an abbreviation  of
412                     one of these.  If what is units, the view adjusts left or
413                     right by number average-width characters on the  display;
414                     if  it  is  pages then the view adjusts by number screen‐
415                     fuls.  If number is negative then characters  farther  to
416                     the  left become visible;  if it is positive then charac‐
417                     ters farther to the right become visible.
418

DEFAULT BINDINGS

420       Tk automatically creates class bindings for entries that give them  the
421       following default behavior. In the descriptions below, “word” refers to
422       a contiguous group of letters, digits, or “_” characters, or any single
423       character other than these.
424
425       [1]    Clicking  mouse  button  1  positions  the insertion cursor just
426              before the character underneath the mouse cursor, sets the input
427              focus  to  this  widget, and clears any selection in the widget.
428              Dragging with mouse button 1 strokes out a selection between the
429              insertion cursor and the character under the mouse.
430
431       [2]    Double-clicking  with  mouse button 1 selects the word under the
432              mouse and positions the insertion cursor at the end of the word.
433              Dragging  after  a double click will stroke out a selection con‐
434              sisting of whole words.
435
436       [3]    Triple-clicking with mouse button 1 selects all of the  text  in
437              the  entry  and positions the insertion cursor at the end of the
438              line.
439
440       [4]    The ends of the selection can be adjusted by dragging with mouse
441              button  1 while the Shift key is down;  this will adjust the end
442              of the selection that was nearest to the mouse cursor when  but‐
443              ton 1 was pressed.  If the button is double-clicked before drag‐
444              ging then the selection will  be  adjusted  in  units  of  whole
445              words.
446
447       [5]    Clicking  mouse button 1 with the Control key down will position
448              the insertion cursor in the entry without affecting  the  selec‐
449              tion.
450
451       [6]    If  any  normal  printing characters are typed in an entry, they
452              are inserted at the point of the insertion cursor.
453
454       [7]    The view in the entry can be adjusted  by  dragging  with  mouse
455              button  2.   If  mouse  button  2  is clicked without moving the
456              mouse, the selection is copied into the entry at the position of
457              the mouse cursor.
458
459       [8]    If  the  mouse  is dragged out of the entry on the left or right
460              sides while button 1 is pressed, the  entry  will  automatically
461              scroll  to  make  more  text visible (if there is more text off-
462              screen on the side where the mouse left the window).
463
464       [9]    The Left and Right keys move the insertion cursor one  character
465              to  the  left  or  right;   they also clear any selection in the
466              entry and set the selection anchor.  If Left or Right  is  typed
467              with the Shift key down, then the insertion cursor moves and the
468              selection is extended to include the  new  character.   Control-
469              Left  and  Control-Right move the insertion cursor by words, and
470              Control-Shift-Left and Control-Shift-Right  move  the  insertion
471              cursor  by  words  and also extend the selection.  Control-b and
472              Control-f behave the  same  as  Left  and  Right,  respectively.
473              Meta-b  and  Meta-f behave the same as Control-Left and Control-
474              Right, respectively.
475
476       [10]   The Home key, or Control-a, will move the  insertion  cursor  to
477              the beginning of the entry and clear any selection in the entry.
478              Shift-Home moves the insertion cursor to the  beginning  of  the
479              entry and also extends the selection to that point.
480
481       [11]   The End key, or Control-e, will move the insertion cursor to the
482              end of the entry and clear any selection in the  entry.   Shift-
483              End  moves  the  cursor  to the end and extends the selection to
484              that point.
485
486       [12]   The Select key and Control-Space set the selection anchor to the
487              position  of  the insertion cursor.  They do not affect the cur‐
488              rent selection.  Shift-Select and Control-Shift-Space adjust the
489              selection  to  the  current  position  of  the insertion cursor,
490              selecting from the anchor to the insertion cursor if  there  was
491              not any selection previously.
492
493       [13]   Control-/ selects all the text in the entry.
494
495       [14]   Control-\ clears any selection in the entry.
496
497       [15]   The  F16  key (labelled Copy on many Sun workstations) or Meta-w
498              copies the selection in the widget to the clipboard, if there is
499              a selection.
500
501       [16]   The F20 key (labelled Cut on many Sun workstations) or Control-w
502              copies the selection in the widget to the clipboard and  deletes
503              the  selection.   If  there  is  no selection in the widget then
504              these keys have no effect.
505
506       [17]   The F18 key (labelled Paste on many Sun  workstations)  or  Con‐
507              trol-y  inserts the contents of the clipboard at the position of
508              the insertion cursor.
509
510       [18]   The Delete key deletes the selection, if there  is  one  in  the
511              entry.   If  there  is no selection, it deletes the character to
512              the right of the insertion cursor.
513
514       [19]   The BackSpace key and Control-h delete the selection,  if  there
515              is  one  in the entry.  If there is no selection, it deletes the
516              character to the left of the insertion cursor.
517
518       [20]   Control-d deletes the character to the right  of  the  insertion
519              cursor.
520
521       [21]   Meta-d deletes the word to the right of the insertion cursor.
522
523       [22]   Control-k  deletes all the characters to the right of the inser‐
524              tion cursor.
525
526       [23]   Control-t reverses the order of the two characters to the  right
527              of the insertion cursor.
528
529       If the entry is disabled using the -state option, then the entry's view
530       can still be adjusted and text in the entry can still be selected,  but
531       no  insertion  cursor  will be displayed and no text modifications will
532       take place except if the entry  is  linked  to  a  variable  using  the
533       -textvariable  option,  in  which  case any changes to the variable are
534       reflected by the entry whatever the value of its -state option.
535
536       The behavior of entries can be changed by  defining  new  bindings  for
537       individual widgets or by redefining the class bindings.
538

SEE ALSO

540       ttk::entry(n)
541

KEYWORDS

543       entry, widget
544
545
546
547Tk                                    8.3                             entry(n)
Impressum