ENTRY(9)                                                 ENTRY(9)

     NAME
          entry - Create and manipulate entry widgets

     SYNOPSIS
          entry pathName ?options?

     STANDARD OPTIONS
          -background  -highlightcolor     -selectbackground
          -borderwidth -highlightthickness -selectforeground
          -font        -justify            -takefocus
          -foreground  -relief             -xscrollcommand

     WIDGET-SPECIFIC OPTIONS
          -show string
               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.

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

          -width dist
               Specifies an integer value indicating the desired width
               of the entry window.

     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 to configure aspects of the entry such as its
          colours, 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.

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

     Page 1                       Plan 9             (printed 3/28/24)

     ENTRY(9)                                                 ENTRY(9)

          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 win-
          dow.  Entries use the standard xscrollcommand mechanism for
          interacting with scrollbars (see the description of the
          xscrollcommand option for details).

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

          Many of the widget commands for entries take one or more
          indices as arguments.  An index specifies a particular char-
          acter 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 immedi-
                      ately 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 exam-
                      ple, ``@0'' indicates the left-most character in
                      the window.

     Page 2                       Plan 9             (printed 3/28/24)

     ENTRY(9)                                                 ENTRY(9)

          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 wid-
               get.  If no option is specified, returns a list of all
               of the available options for pathName.  If one or more
               option-value pairs are specified, then the command mod-
               ifies 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 com-
               mand 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 charac-
               ter indicated by index.  Returns an empty string.

          pathName see index
               Adjusts the view in the window so that the character

     Page 3                       Plan 9             (printed 3/28/24)

     ENTRY(9)                                                 ENTRY(9)

               given by index is completely visible.

          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 cur-
                    rently in the entry, then a new selection is cre-
                    ated 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 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

     Page 4                       Plan 9             (printed 3/28/24)

     ENTRY(9)                                                 ENTRY(9)

                    widget.  Returns an empty string.

          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 ele-
                    ment 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 -xscrollcom-
                    mand option.

               pathName xview index
                    Adjusts the view in the window so that the charac-
                    ter 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 charac-
                    ter 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.  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 bindings for entries that give them
          the following default behaviour.  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

     Page 5                       Plan 9             (printed 3/28/24)

     ENTRY(9)                                                 ENTRY(9)

               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.

          [3]  If any normal printing characters are typed in an
               entry, the current selection is deleted, and they are
               inserted at the point of the insertion cursor

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

          [5]  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.
               Control-b and Control-f behave the same as Left and
               Right, respectively.

          [6]  The Home key, or Control-a, will move the insertion
               cursor to the beginning of the entry and clear any
               selection in the entry.

          [7]  The End key, or Control-e, will move the insertion cur-
               sor to the end of the entry and clear any selection in
               the entry.

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

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

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

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

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

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

          [14] Control-w deletes the word to the left of the insertion
               cursor.

          If the entry is disabled using the -state option, then the

     Page 6                       Plan 9             (printed 3/28/24)

     ENTRY(9)                                                 ENTRY(9)

          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 behaviour of entries can be changed by defining new
          bindings for individual widgets.

     SEE ALSO
          options(9), types(9)

     Page 7                       Plan 9             (printed 3/28/24)