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 “*”.  This
41       is useful, for example, if the entry is to be used to enter a password.
42       If  characters  in  the  entry  are  selected and copied elsewhere, the
43       information copied will be what is displayed, not the true contents  of
44       the entry.  [-state state] Specifies one of three states for the entry:
45       normal, disabled, or readonly.  If the  entry  is  readonly,  then  the
46       value  may not be changed using widget commands and no insertion cursor
47       will be displayed, even if the input focus is in the widget;  the  con‐
48       tents  of  the widget may still be selected.  If the entry is disabled,
49       the value may not be changed, no insertion cursor  will  be  displayed,
50       the  contents will not be selectable, and the entry may be displayed in
51       a different color, depending on the values of  the  -disabledforeground
52       and  -disabledbackground  options.   [-validate validate] Specifies the
53       mode in which validation should operate: none,  focus,  focusin,  focu‐
54       sout, key, or all.  It defaults to none.  When you want validation, you
55       must explicitly state which mode you wish to use.  See Validation below
56       for  more.   [-validatecommand  or  -vcmd validateCommand]  Specifies a
57       script to eval when you want to validate the input into the entry  wid‐
58       get.   Setting it to {} disables this feature (the default).  This com‐
59       mand must return a valid Tcl boolean value.  If it returns  0  (or  the
60       valid  Tcl boolean equivalent) then it means you reject the new edition
61       and it will not occur and the invalidCommand will be evaluated if it is
62       set.  If  it  returns  1,  then the new edition occurs.  See Validation
63       below for more information.  [-width width] Specifies an integer  value
64       indicating the desired width of the entry window, in average-size char‐
65       acters 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

DESCRIPTION

71       The entry command creates a new window (given by the pathName argument)
72       and  makes  it  into  an  entry  widget.  Additional options, described
73       above, may be specified on the command line or in the  option  database
74       to configure aspects of the entry such as its colors, font, and relief.
75       The entry command returns its pathName argument.  At the time this com‐
76       mand  is  invoked,  there  must  not exist a window named pathName, but
77       pathName's parent must exist.
78
79       An entry is a widget that displays a one-line text  string  and  allows
80       that  string  to be edited using widget commands described below, which
81       are typically bound to keystrokes and mouse actions.  When  first  cre‐
82       ated,  an  entry's  string  is  empty.   A  portion of the entry may be
83       selected as described below.  If an entry is  exporting  its  selection
84       (see the exportSelection option), then it will observe the standard X11
85       protocols for handling the selection;  entry selections  are  available
86       as type STRING.  Entries also observe the standard Tk rules for dealing
87       with the input focus.  When an entry has the input focus it displays an
88       insertion cursor to indicate where new characters will be inserted.
89
90       Entries  are  capable  of  displaying  strings that are too long to fit
91       entirely within the widget's window.  In this case, only a  portion  of
92       the  string will be displayed;  commands described below may be used to
93       change the view in the window.  Entries use the standard xScrollCommand
94       mechanism  for  interacting with scrollbars (see the description of the
95       xScrollCommand option for details).  They  also  support  scanning,  as
96       described below.
97

VALIDATION

99       Validation  works  by  setting  the  validateCommand option to a script
100       which will be evaluated according to the validate option as follows:
101
102       none      Default.  This means no validation will occur.
103
104       focus     validateCommand will be called when  the  entry  receives  or
105                 loses focus.
106
107       focusin   validateCommand will be called when the entry receives focus.
108
109       focusout  validateCommand will be called when the entry loses focus.
110
111       key       validateCommand will be called when the entry is edited.
112
113       all       validateCommand will be called for all above conditions.
114
115       It  is possible to perform percent substitutions on the validateCommand
116       and invalidCommand, just as you would in a bind script.  The  following
117       substitutions are recognized:
118
119       %d   Type  of  action:  1  for  insert,  0 for delete, or -1 for focus,
120            forced or textvariable validation.
121
122       %i   Index of char string to be inserted/deleted, if any, otherwise -1.
123
124       %P   The value of the entry if the edit is allowed.  If you are config‐
125            uring  the  entry  widget to have a new textvariable, this will be
126            the value of that textvariable.
127
128       %s   The current value of entry prior to editing.
129
130       %S   The text string being inserted/deleted, if any, {} otherwise.
131
132       %v   The type of validation currently set.
133
134       %V   The type of validation that triggered the callback (key,  focusin,
135            focusout, forced).
136
137       %W   The name of the entry widget.
138
139       In  general,  the  textVariable and validateCommand can be dangerous to
140       mix.  Any problems have been overcome so that using the validateCommand
141       will  not  interfere with the traditional behavior of the entry widget.
142       Using the textVariable for read-only purposes will  never  cause  prob‐
143       lems.   The danger comes when you try set the textVariable to something
144       that the validateCommand would not accept,  which  causes  validate  to
145       become  none (the invalidCommand will not be triggered).  The same hap‐
146       pens when an error occurs evaluating the validateCommand.
147
148       Primarily, an error will occur when the validateCommand or  invalidCom‐
149       mand encounters an error in its script while evaluating or validateCom‐
150       mand does not return a valid Tcl boolean value.   The  validate  option
151       will also set itself to none when you edit the entry widget from within
152       either the validateCommand or the invalidCommand.  Such  editions  will
153       override  the  one  that  was being validated.  If you wish to edit the
154       entry widget (for example set it to {})  during  validation  and  still
155       have the validate option set, you should include the command
156              after idle {%W config -validate %v}
157       in  the validateCommand or invalidCommand (whichever one you were edit‐
158       ing the entry widget from).  It is also recommended to not set an asso‐
159       ciated textVariable during validation, as that can cause the entry wid‐
160       get to become out of sync with the textVariable.
161

WIDGET COMMAND

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

DEFAULT BINDINGS

369       Tk  automatically creates class bindings for entries that give them the
370       following default behavior. In the descriptions below, “word” refers to
371       a contiguous group of letters, digits, or “_” characters, or any single
372       character other than these.
373
374       [1]    Clicking mouse button 1  positions  the  insertion  cursor  just
375              before the character underneath the mouse cursor, sets the input
376              focus to this widget, and clears any selection  in  the  widget.
377              Dragging with mouse button 1 strokes out a selection between the
378              insertion cursor and the character under the mouse.
379
380       [2]    Double-clicking with mouse button 1 selects the word  under  the
381              mouse and positions the insertion cursor at the end of the word.
382              Dragging after a double click will stroke out a  selection  con‐
383              sisting of whole words.
384
385       [3]    Triple-clicking  with  mouse button 1 selects all of the text in
386              the entry and positions the insertion cursor at the end  of  the
387              line.
388
389       [4]    The ends of the selection can be adjusted by dragging with mouse
390              button 1 while the Shift key is down;  this will adjust the  end
391              of  the selection that was nearest to the mouse cursor when but‐
392              ton 1 was pressed.  If the button is double-clicked before drag‐
393              ging  then  the  selection  will  be  adjusted in units of whole
394              words.
395
396       [5]    Clicking mouse button 1 with the Control key down will  position
397              the  insertion  cursor in the entry without affecting the selec‐
398              tion.
399
400       [6]    If any normal printing characters are typed in  an  entry,  they
401              are inserted at the point of the insertion cursor.
402
403       [7]    The  view  in  the  entry can be adjusted by dragging with mouse
404              button 2.  If mouse button  2  is  clicked  without  moving  the
405              mouse, the selection is copied into the entry at the position of
406              the mouse cursor.
407
408       [8]    If the mouse is dragged out of the entry on the  left  or  right
409              sides  while  button  1 is pressed, the entry will automatically
410              scroll to make more text visible (if there  is  more  text  off-
411              screen on the side where the mouse left the window).
412
413       [9]    The  Left and Right keys move the insertion cursor one character
414              to the left or right;  they also  clear  any  selection  in  the
415              entry  and  set the selection anchor.  If Left or Right is typed
416              with the Shift key down, then the insertion cursor moves and the
417              selection  is  extended  to include the new character.  Control-
418              Left and Control-Right move the insertion cursor by  words,  and
419              Control-Shift-Left  and  Control-Shift-Right  move the insertion
420              cursor by words and also extend the  selection.   Control-b  and
421              Control-f  behave  the  same  as  Left  and Right, respectively.
422              Meta-b and Meta-f behave the same as Control-Left  and  Control-
423              Right, respectively.
424
425       [10]   The  Home  key,  or Control-a, will move the insertion cursor to
426              the beginning of the entry and clear any selection in the entry.
427              Shift-Home  moves  the  insertion cursor to the beginning of the
428              entry and also extends the selection to that point.
429
430       [11]   The End key, or Control-e, will move the insertion cursor to the
431              end  of  the entry and clear any selection in the entry.  Shift-
432              End moves the cursor to the end and  extends  the  selection  to
433              that point.
434
435       [12]   The Select key and Control-Space set the selection anchor to the
436              position of the insertion cursor.  They do not affect  the  cur‐
437              rent selection.  Shift-Select and Control-Shift-Space adjust the
438              selection to the  current  position  of  the  insertion  cursor,
439              selecting  from  the anchor to the insertion cursor if there was
440              not any selection previously.
441
442       [13]   Control-/ selects all the text in the entry.
443
444       [14]   Control-\ clears any selection in the entry.
445
446       [15]   The F16 key (labelled Copy on many Sun workstations)  or  Meta-w
447              copies the selection in the widget to the clipboard, if there is
448              a selection.
449
450       [16]   The F20 key (labelled Cut on many Sun workstations) or Control-w
451              copies  the selection in the widget to the clipboard and deletes
452              the selection.  If there is no  selection  in  the  widget  then
453              these keys have no effect.
454
455       [17]   The  F18  key  (labelled Paste on many Sun workstations) or Con‐
456              trol-y inserts the contents of the clipboard at the position  of
457              the insertion cursor.
458
459       [18]   The  Delete  key  deletes  the selection, if there is one in the
460              entry.  If there is no selection, it deletes  the  character  to
461              the right of the insertion cursor.
462
463       [19]   The  BackSpace  key and Control-h delete the selection, if there
464              is one in the entry.  If there is no selection, it  deletes  the
465              character to the left of the insertion cursor.
466
467       [20]   Control-d  deletes  the  character to the right of the insertion
468              cursor.
469
470       [21]   Meta-d deletes the word to the right of the insertion cursor.
471
472       [22]   Control-k deletes all the characters to the right of the  inser‐
473              tion cursor.
474
475       [23]   Control-t  reverses the order of the two characters to the right
476              of the insertion cursor.
477
478       If the entry is disabled using the -state option, then the entry's view
479       can  still be adjusted and text in the entry can still be selected, but
480       no insertion cursor will be displayed and no  text  modifications  will
481       take  place  except  if  the  entry  is  linked to a variable using the
482       -textvariable option, in which case any changes  to  the  variable  are
483       reflected by the entry whatever the value of its -state option.
484
485       The  behavior  of  entries  can be changed by defining new bindings for
486       individual widgets or by redefining the class bindings.
487

SEE ALSO

489       ttk::entry(n)
490

KEYWORDS

492       entry, widget
493
494
495
496Tk                                    8.3                             entry(n)
Impressum