NAME
       entry - Create and manipulate entry widgets

SYNOPSIS
       entry pathName ?options?

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

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

WIDGET-SPECIFIC OPTIONS
       Command-Line Name:-disabledbackground
       Database Name:  disabledBackground
       Database Class: DisabledBackground

              Specifies the background  color  to  use  when  the
              entry  is  disabled.   If  this option is the empty
              string, the normal background color is used.

       Command-Line Name:-disabledforeground
       Database Name:  disabledForeground
       Database Class: DisabledForeground

              Specifies the foreground  color  to  use  when  the
              entry  is  disabled.   If  this option is the empty
              string, the normal foreground color is used.

       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:-readonlybackground
       Database Name:  readonlyBackground
       Database Class: ReadonlyBackground

              Specifies the background  color  to  use  when  the
              entry  is  readonly.   If  this option is the empty
              string, the normal background color is used.

       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 three states for the entry:  nor-
              mal, disabled, or readonly.  If the entry is  read-
              only,  then the value may not be changed using wid-
              get commands and no insertion cursor will  be  dis-
              played,  even  if the input focus is in the widget;
              the contents of the widget may still  be  selected.
              If  the  entry  is  disabled,  the value may not be
              changed, no insertion cursor will be displayed, the
              contents  will not be selectable, and the entry may
              be displayed in a different color, depending on the
              values  of  the  -disabledforeground and -disabled-
              background options.

       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 possible 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 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 except
       if  the entry is linked to a variable using the -textvari-
       able option, in which case any changes to the variable are
       reflected  by  the  entry whatever the value of its -state
       option.

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


KEYWORDS
