NAME
       entry - Create and manipulate entry widgets

SYNOPSIS
       entry pathName ?options?

STANDARD OPTIONS
       -background     -highlightbackground           -insertontime-selectforeground
       -borderwidth    -highlightcolor                -insertwidth-takefocus
       -cursor         -highlightthickness            -justify-textvariable
       -exportselection               -insertbackground-relief-xscrollcommand
       -font           -insertborderwidth             -selectbackground
       -foreground     -insertofftime -selectborderwidth

       See  the  options manual entry for details on the standard
       options.

WIDGET-SPECIFIC OPTIONS
       Command-Line Name:-invalidcommand or -invcmd
       Database Name:  invalidCommand
       Database Class: InvalidCommand

              Specifies a script  to  eval  when  validateCommand
              returns  0.  Setting it to {} disables this feature
              (the default).  The best use of this option  is  to
              set  it  to  bell.   See  Validation below for more
              information.

       Command-Line Name:-show
       Database Name:  show
       Database Class: Show

              If this option is specified, then the true contents
              of  the  entry  are  not  displayed  in the window.
              Instead, each character in the entry's  value  will
              be displayed as the first character in the value of
              this option, such as ``*''.  This  is  useful,  for
              example,  if  the  entry  is  to be used to enter a
              password.  If characters in the entry are  selected
              and  copied  elsewhere, the information copied will
              be what is displayed, not the true contents of  the
              entry.

       Command-Line Name:-state
       Database Name:  state
       Database Class: State

              Specifies  one of two states for the entry:  normal
              or disabled.  If the entry  is  disabled  then  the
              value  may not be changed using widget commands and
              no insertion cursor will be displayed, even if  the
              input focus is in the widget.

       Command-Line Name:-validate
       Database Name:  validate
       Database Class: Validate

              Specifies  the  mode  in  which  validation  should
              operate: none, focus, focusin,  focusout,  key,  or
              all.    It   defaults   to  none.   When  you  want
              validation, you must explicitly  state  which  mode
              you wish to use.  See Validation below for more.

       Command-Line Name:-validatecommand or -vcmd
       Database Name:  validateCommand
       Database Class: ValidateCommand

              Specifies  a  script  to  eval  when  you  want  to
              validate the input into the entry widget.   Setting
              it to {} disables this feature (the default).  This
              command must return a valid tcl boolean value.   If
              it  returns 0 (or the valid tcl boolean equivalent)
              then it means you reject the  new  edition  and  it
              will  not  occur  and  the  invalidCommand  will be
              evaluated if it is set. If it returns 1,  then  the
              new  edition occurs.  See Validation below for more
              information.

       Command-Line Name:-width
       Database Name:  width
       Database Class: Width

              Specifies an integer value indicating  the  desired
              width   of   the   entry  window,  in  average-size
              characters of the widget's font.  If the  value  is
              less than or equal to zero, the widget picks a size
              just large enough to hold its current text.


DESCRIPTION
       The entry command creates  a  new  window  (given  by  the
       pathName  argument)  and  makes  it  into an entry widget.
       Additional options, described above, may be  specified  on
       the  command  line  or in the option database to configure
       aspects of the entry such as its colors, font, and relief.
       The  entry  command returns its pathName argument.  At the
       time this command is  invoked,  there  must  not  exist  a
       window named pathName, but pathName's parent must exist.

       An  entry is a widget that displays a one-line text string
       and allows that string to be edited using widget  commands
       described  below,  which are typically bound to keystrokes
       and mouse actions.  When first created, an entry's  string
       is  empty.   A  portion  of  the  entry may be selected as
       described below.  If an entry is exporting  its  selection
       (see the exportSelection option), then it will observe the
       standard X11 protocols for handling the selection;   entry
       selections  are  available  as  type STRING.  Entries also
       observe the standard Tk rules for dealing with  the  input
       focus.   When  an entry has the input focus it displays an
       insertion cursor to indicate where new characters will  be
       inserted.

       Entries  are  capable  of  displaying strings that are too
       long to fit entirely within the widget's window.  In  this
       case,  only  a  portion  of  the string will be displayed;
       commands described below may be used to change the view in
       the  window.   Entries  use  the  standard  xScrollCommand
       mechanism  for  interacting  with  scrollbars   (see   the
       description  of  the  xScrollCommand  option for details).
       They also support scanning, as described below.


VALIDATION
       Validation works by setting the validateCommand option  to
       a script which will be evaluated according to the validate
       option as follows:


       none      Default.  This means no validation will occur.

       focus     validateCommand will be called  when  the  entry
                 receives or loses focus.

       focusin   validateCommand  will  be  called when the entry
                 receives focus.

       focusout  validateCommand will be called  when  the  entry
                 loses focus.

       key       validateCommand will be called when the entry is
                 edited.

       all       validateCommand will be  called  for  all  above
                 conditions.

       It  is  posible  to  perform  percent substitutions on the
       validateCommand and invalidCommand, just as you would in a
       bind script.  The following substitutions are recognized:


       %d   Type of action: 1 for insert, 0 for delete, or -1 for
            focus, forced or textvariable validation.

       %i   Index of char string to be inserted/deleted, if  any,
            otherwise -1.

       %P   The  value of the entry should edition occur.  If you
            are configuring  the  entry  widget  to  have  a  new
            textvariable,   this   will  be  the  value  of  that
            textvariable.

       %s   The current value of entry before edition.

       %S   The text string being inserted/deleted,  if  any,  {}
            otherwise.

       %v   The type of validation currently set.

       %V   The  type  of  validation that triggered the callback
            (key, focusin, focusout, forced).

       %W   The name of the entry widget.

       In general, the textVariable and  validateCommand  can  be
       dangerous to mix.  Any problems have been overcome so that
       using the validateCommand  will  not  interfere  with  the
       traditional  behavior  of  the  entry  widget.   Using the
       textVariable  for  read-only  purposes  will  never  cause
       problems.    The   danger  comes  when  you  try  set  the
       textVariable to something that the  validateCommand  would
       not  accept,  which  causes  validate  to become none (the
       invalidCommand will not be triggered).  The  same  happens
       when an error occurs evaluating the validateCommand.

       Primarily, an error will occur when the validateCommand or
       invalidCommand encounters an error  in  its  script  while
       evaluating  or validateCommand does not return a valid tcl
       boolean value.  The validate option will also  set  itself
       to  none when you edit the entry widget from within either
       the validateCommand or the invalidCommand.  Such  editions
       will  override  the  one that was being validated.  If you
       wish to edit the entry widget (for example set it  to  {})
       during  validation and still have the validate option set,
       you should include the command
                   after idle {%W config -validate %v}
       in the validateCommand or  invalidCommand  (whichever  one
       you  were  editing  the  entry  widget  from).  It is also
       recommended to not set an associated  textVariable  during
       validation,  as  that can cause the entry widget to become
       out of sync with the textVariable.


WIDGET COMMAND
       The entry command creates a new Tcl command whose name  is
       pathName.   This  command  may  be  used to invoke various
       operations on the widget.  It has  the  following  general
       form:
              pathName option ?arg arg ...?
       Option  and  the  args determine the exact behavior of the
       command.

       Many of the widget commands for entries take one  or  more
       indices  as  arguments.   An  index specifies a particular
       character in the entry's string, in any of  the  following
       ways:

       number      Specifies  the character as a numerical index,
                   where 0 corresponds to the first character  in
                   the string.

       anchor      Indicates  the anchor point for the selection,
                   which is set with the select from  and  select
                   adjust widget commands.

       end         Indicates  the  character  just after the last
                   one in the entry's string.  This is equivalent
                   to  specifying  a numerical index equal to the
                   length of the entry's string.

       insert      Indicates  the  character  adjacent   to   and
                   immediately following the insertion cursor.

       sel.first   Indicates   the   first   character   in   the
                   selection.  It is an error to use this form if
                   the selection isn't in the entry window.

       sel.last    Indicates  the  character  just after the last
                   one in the selection.  It is an error  to  use
                   this  form if the selection isn't in the entry
                   window.

       @number     In this form,  number  is  treated  as  an  x-
                   coordinate   in   the   entry's  window;   the
                   character spanning that x-coordinate is  used.
                   For  example,  ``@0''  indicates the left-most
                   character in the window.

       Abbreviations may be used for any of the forms above, e.g.
       ``e''  or ``sel.f''.  In general, out-of-range indices are
       automatically rounded to the nearest legal value.

       The following commands are possible for entry widgets:

       pathName bbox index
              Returns a  list  of  four  numbers  describing  the
              bounding  box of the character given by index.  The
              first two elements of the list give  the  x  and  y
              coordinates  of the upper-left corner of the screen
              area covered by the character (in  pixels  relative
              to  the  widget) and the last two elements give the
              width and height of the character, in pixels.   The
              bounding  box  may  refer  to  a region outside the
              visible area of the window.

       pathName cget option
              Returns the  current  value  of  the  configuration
              option given by option.  Option may have any of the
              values accepted by the entry command.

       pathName configure ?option? ?value option value ...?
              Query or modify the configuration  options  of  the
              widget.   If no option is specified, returns a list
              describing  all  of  the  available   options   for
              pathName  (see  Tk_ConfigureInfo for information on
              the format of this list).  If option  is  specified
              with  no  value,  then  the  command returns a list
              describing the one named option (this list will  be
              identical to the corresponding sublist of the value
              returned if no option is  specified).   If  one  or
              more  option-value  pairs  are  specified, then the
              command modifies the given widget option(s) to have
              the  given  value(s);   in  this  case  the command
              returns an empty string.  Option may  have  any  of
              the values accepted by the entry command.

       pathName delete first ?last?
              Delete one or more elements of the entry.  First is
              the index of the first  character  to  delete,  and
              last  is  the index of the character just after the
              last one to delete.  If  last  isn't  specified  it
              defaults  to  first+1,  i.e.  a single character is
              deleted.  This command returns an empty string.

       pathName get
              Returns the entry's string.

       pathName icursor index
              Arrange for the insertion cursor  to  be  displayed
              just  before the character given by index.  Returns
              an empty string.

       pathName index index
              Returns the numerical index corresponding to index.

       pathName insert index string
              Insert  the  characters  of  string just before the
              character indicated by  index.   Returns  an  empty
              string.

       pathName scan option args
              This  command  is  used  to  implement  scanning on
              entries.  It has two forms, depending on option:

              pathName scan mark x
                     Records x and the current view in the  entry
                     window;  used in conjunction with later scan
                     dragto commands.  Typically this command  is
                     associated  with a mouse button press in the
                     widget.  It returns an empty string.

              pathName scan dragto x
                     This command computes the difference between
                     its  x  argument  and  the x argument to the
                     last scan mark command for the  widget.   It
                     then  adjusts  the  view left or right by 10
                     times the difference in x-coordinates.  This
                     command  is  typically associated with mouse
                     motion events in the widget, to produce  the
                     effect  of  dragging the entry at high speed
                     through the window.  The return value is  an
                     empty string.

       pathName selection option arg
              This command is used to adjust the selection within
              an entry.   It  has  several  forms,  depending  on
              option:

              pathName selection adjust index
                     Locate  the  end of the selection nearest to
                     the character given  by  index,  and  adjust
                     that  end  of  the  selection to be at index
                     (i.e including but not going beyond  index).
                     The  other  end of the selection is made the
                     anchor point for future select to  commands.
                     If  the  selection  isn't  currently  in the
                     entry, then a new selection  is  created  to
                     include the characters between index and the
                     most   recent   selection   anchor    point,
                     inclusive.  Returns an empty string.

              pathName selection clear
                     Clear  the  selection  if it is currently in
                     this widget.  If the selection isn't in this
                     widget  then  the  command  has  no  effect.
                     Returns an empty string.

              pathName selection from index
                     Set  the  selection  anchor  point  to  just
                     before   the   character   given  by  index.
                     Doesn't change the  selection.   Returns  an
                     empty string.

              pathName selection present
                     Returns   1   if  there  is  are  characters
                     selected in  the  entry,  0  if  nothing  is
                     selected.

              pathName selection range start end
                     Sets the selection to include the characters
                     starting with the one indexed by  start  and
                     ending with the one just before end.  If end
                     refers to the same character as start or  an
                     earlier  one,  then the entry's selection is
                     cleared.

              pathName selection to index
                     If index is before the anchor point, set the
                     selection to the characters from index up to
                     but not  including  the  anchor  point.   If
                     index  is  the  same as the anchor point, do
                     nothing.   If  index  is  after  the  anchor
                     point,  set  the selection to the characters
                     from  the  anchor  point  up  to   but   not
                     including   index.    The  anchor  point  is
                     determined by the most recent select from or
                     select  adjust  command  in this widget.  If
                     the selection isn't in this  widget  then  a
                     new  selection  is  created  using  the most
                     recent  anchor  point  specified   for   the
                     widget.  Returns an empty string.

       pathName validate
              This  command is used to force an evaluation of the
              validateCommand  independent  of   the   conditions
              specified  by the validate option.  This is done by
              temporarily setting the validate option to all.  It
              returns 0 or 1.

       pathName xview args
              This  command  is  used  to  query  and  change the
              horizontal position of the  text  in  the  widget's
              window.  It can take any of the following forms:

              pathName xview
                     Returns  a  list  containing  two  elements.
                     Each element is a real  fraction  between  0
                     and   1;    together   they   describe   the
                     horizontal  span  that  is  visible  in  the
                     window.   For  example, if the first element
                     is .2 and the second element is .6,  20%  of
                     the  entry's text is off-screen to the left,
                     the middle 40% is visible in the window, and
                     40%  of the text is off-screen to the right.
                     These  are  the  same   values   passed   to
                     scrollbars via the -xscrollcommand option.

              pathName xview index
                     Adjusts  the  view in the window so that the
                     character given by index is displayed at the
                     left edge of the window.

              pathName xview moveto fraction
                     Adjusts  the  view in the window so that the
                     character fraction of the  way  through  the
                     text appears at the left edge of the window.
                     Fraction must be a fraction between 0 and 1.

              pathName xview scroll number what
                     This  command  shifts the view in the window
                     left or right according to number and  what.
                     Number  must  be  an  integer.  What must be
                     either units or pages or an abbreviation  of
                     one  of  these.   If what is units, the view
                     adjusts left or  right  by  number  average-
                     width  characters  on the display;  if it is
                     pages  then  the  view  adjusts  by   number
                     screenfuls.   If  number  is  negative  then
                     characters  farther  to  the   left   become
                     visible;   if it is positive then characters
                     farther to the right become visible.


DEFAULT BINDINGS
       Tk automatically creates class bindings for  entries  that
       give   them   the  following  default  behavior.   In  the
       descriptions below, ``word'' refers to a contiguous  group
       of  letters,  digits,  or  ``_'' characters, or any single
       character other than these.

       [1]    Clicking mouse button  1  positions  the  insertion
              cursor  just  before  the  character underneath the
              mouse cursor, sets the input focus to this  widget,
              and  clears  any selection in the widget.  Dragging
              with mouse button 1 strokes out a selection between
              the  insertion  cursor  and the character under the
              mouse.

       [2]    Double-clicking with mouse  button  1  selects  the
              word  under  the  mouse and positions the insertion
              cursor at the  beginning  of  the  word.   Dragging
              after  a  double  click will stroke out a selection
              consisting of whole words.

       [3]    Triple-clicking with mouse button 1 selects all  of
              the  text  in the entry and positions the insertion
              cursor before the first character.

       [4]    The ends  of  the  selection  can  be  adjusted  by
              dragging with mouse button 1 while the Shift key is
              down;  this will adjust the end  of  the  selection
              that  was nearest to the mouse cursor when button 1
              was  pressed.   If  the  button  is  double-clicked
              before dragging then the selection will be adjusted
              in units of whole words.

       [5]    Clicking mouse button 1 with the Control  key  down
              will  position  the  insertion  cursor in the entry
              without affecting the selection.

       [6]    If any normal printing characters are typed  in  an
              entry,  they  are  inserted  at  the  point  of the
              insertion cursor.

       [7]    The view in the entry can be adjusted  by  dragging
              with  mouse button 2.  If mouse button 2 is clicked
              without moving the mouse, the selection  is  copied
              into the entry at the position of the mouse cursor.

       [8]    If the mouse is dragged out of  the  entry  on  the
              left  or right sides while button 1 is pressed, the
              entry will automatically scroll to make  more  text
              visible  (if  there  is more text off-screen on the
              side where the mouse left the window).

       [9]    The Left and Right keys move the  insertion  cursor
              one  character  to  the  left  or right;  they also
              clear any  selection  in  the  entry  and  set  the
              selection  anchor.   If Left or Right is typed with
              the Shift key down, then the insertion cursor moves
              and  the  selection  is extended to include the new
              character.  Control-Left and Control-Right move the
              insertion  cursor  by words, and Control-Shift-Left
              and Control-Shift-Right move the  insertion  cursor
              by  words and also extend the selection.  Control-b
              and Control-f behave the same as  Left  and  Right,
              respectively.  Meta-b and Meta-f behave the same as
              Control-Left and Control-Right, respectively.

       [10]   The Home key, or Control-a, will move the insertion
              cursor  to the beginning of the entry and clear any
              selection  in  the  entry.   Shift-Home  moves  the
              insertion  cursor to the beginning of the entry and
              also extends the selection to that point.

       [11]   The End key, or Control-e, will move the  insertion
              cursor  to  the  end  of  the  entry  and clear any
              selection in the entry.  Shift-End moves the cursor
              to the end and extends the selection to that point.

       [12]   The Select key and Control-Space set the  selection
              anchor  to  the  position  of the insertion cursor.
              They don't affect the  current  selection.   Shift-
              Select and Control-Shift-Space adjust the selection
              to the current position of  the  insertion  cursor,
              selecting  from  the anchor to the insertion cursor
              if there was not any selection previously.

       [13]   Control-/ selects all the text in the entry.

       [14]   Control-\ clears any selection in the entry.

       [15]   The  F16   key   (labelled   Copy   on   many   Sun
              workstations) or Meta-w copies the selection in the
              widget to the clipboard, if there is a selection.

       [16]   The F20 key (labelled Cut on many Sun workstations)
              or  Control-w copies the selection in the widget to
              the clipboard and deletes the selection.  If  there
              is  no selection in the widget then these keys have
              no effect.

       [17]   The  F18  key   (labelled   Paste   on   many   Sun
              workstations)  or Control-y inserts the contents of
              the clipboard at  the  position  of  the  insertion
              cursor.

       [18]   The  Delete  key deletes the selection, if there is
              one in the entry.  If there  is  no  selection,  it
              deletes the character to the right of the insertion
              cursor.

       [19]   The  BackSpace  key  and   Control-h   delete   the
              selection,  if there is one in the entry.  If there
              is no selection, it deletes the  character  to  the
              left of the insertion cursor.

       [20]   Control-d deletes the character to the right of the
              insertion cursor.

       [21]   Meta-d  deletes  the  word  to  the  right  of  the
              insertion cursor.

       [22]   Control-k  deletes  all the characters to the right
              of the insertion cursor.

       [23]   Control-t reverses the order of the two  characters
              to the right of the insertion cursor.

       If the entry is disabled using the -state option, then the
       entry's view can still be adjusted and text in  the  entry
       can  still  be  selected,  but no insertion cursor will be
       displayed and no text modifications will take place.

       The behavior of entries can be  changed  by  defining  new
       bindings for individual widgets or by redefining the class
       bindings.


KEYWORDS
