NAME
       entry - Create and manipulate entry widgets

SYNOPSIS
       entry pathName ?options?

STANDARD OPTIONS
       background      foreground     insertWidth     selectForeground
       borderWidth     insertBackground               relieftextVariable
       cursor          insertBorderWidth              scrollCommand
       exportSelection insertOffTime  selectBackground
       font            insertOnTime   selectBorderWidth

       See  the ``options'' manual entry for details on the stan-
       dard options.

WIDGET-SPECIFIC OPTIONS
       Name:           state
       Class:          State
       Command-Line Switch:-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.

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

              Specifies an integer value indicating  the  desired
              width  of the entry window, in average-size charac-
              ters of the widget's font.


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 scrollCommand mecha-
       nism for interacting with scrollbars (see the  description
       of  the scrollCommand option for details).  They also sup-
       port scanning, as described below.


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.

       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 last character in the selection.
                   It is an error to use this form if the  selec-
                   tion isn't in the entry window.

       @number     In  this  form,  number  is  treated  as an x-
                   coordinate in the entry's window;  the charac-
                   ter  spanning  that x-coordinate is used.  For
                   example, ``@0'' indicates the left-most  char-
                   acter 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 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
              and last are indices of of the first and last char-
              acters in the range to be deleted.   If last  isn't
              specified it defaults to first, i.e. a single char-
              acter 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 select option arg
              This command is used to adjust the selection within
              an  entry.   It  has  several  forms,  depending on
              option:

              pathName select 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 select 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 select 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 select to index
                     Set the selection to consist of the elements
                     from  the  anchor  point  to  element index,
                     inclusive.  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 view index
              Adjust the view in the entry so that element  index
              is  at  the  left  edge  of the window.  Returns an
              empty string.


DEFAULT BINDINGS
       Tk automatically creates class bindings for  entries  that
       give them the following default behavior:

       [1]    Clicking  mouse  button 1 in an entry positions the
              insertion cursor just before the  character  under-
              neath  the mouse cursor and sets the input focus to
              this widget.

       [2]    Dragging with mouse button 1 strokes out  a  selec-
              tion between the insertion cursor and the character
              under the mouse.

       [3]    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.

       [4]    The view in the entry can be adjusted  by  dragging
              with mouse button 2.

       [5]    If  the input focus is in an entry widget and char-
              acters are typed on the  keyboard,  the  characters
              are inserted just before the insertion cursor.

       [6]    Control-h  and  the Backspace and Delete keys erase
              the character just before the insertion cursor.

       [7]    Control-w erases the word just before the insertion
              cursor.

       [8]    Control-u clears the entry to an empty string.

       [9]    Control-v inserts the current selection just before
              the insertion cursor.

       [10]   Control-d  deletes  the  selected  characters;   an
              error  occurs  if the selection is not in this wid-
              get.

       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
