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 oper-
              ate: 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 vali-
              date 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 eval-
              uated 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 charac-
              ters 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 path-
       Name  argument)  and makes it into an entry widget.  Addi-
       tional 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  win-
       dow 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 mech-
       anism for interacting with scrollbars (see the description
       of the xScrollCommand option for details).  They also sup-
       port 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 val-
       idateCommand 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 tra-
       ditional   behavior   of  the  entry  widget.   Using  the
       textVariable for read-only purposes will never cause prob-
       lems.   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 rec-
       ommended to not set an associated textVariable during val-
       idation,  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  imme-
                   diately following the insertion cursor.

       sel.first   Indicates  the  first  character in the selec-
                   tion.  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-coor-
                   dinate  in  the entry's window;  the character
                   spanning that x-coordinate is used.  For exam-
                   ple,  ``@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 vis-
              ible 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  path-
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list).  If option is specified  with
              no  value, then the command returns a list describ-
              ing the one named option (this list will be identi-
              cal  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,  inclu-
                     sive.  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  includ-
                     ing  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 spec-
              ified by the validate option.  This is done by tem-
              porarily setting the validate option  to  all.   It
              returns 0 or 1.

       pathName xview args
              This  command is used to query and change the hori-
              zontal 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 horizon-
                     tal 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  visi-
                     ble;  if it is positive then characters far-
                     ther to the right become visible.


DEFAULT BINDINGS
       Tk automatically creates class bindings for  entries  that
       give them the following default behavior.  In the descrip-
       tions below, ``word'' refers to a contiguous group of let-
       ters, 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  drag-
              ging  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 inser-
              tion 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 selec-
              tion  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 char-
              acter.  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 selec-
              tion 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 worksta-
              tions) 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 worksta-
              tions) 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 selec-
              tion, 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 inser-
              tion 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
       entry, widget
