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:-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:-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.


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
              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, 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 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
       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 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
