ENTRY(9) ENTRY(9)
NAME
entry - Create and manipulate entry widgets
SYNOPSIS
entry pathName ?options?
STANDARD OPTIONS
-background -justify -selectforeground
-borderwidth -relief -xscrollcommand
-font -selectbackground
-foreground -selectborderwidth
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. 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.
-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, in average-size characters 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 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, but pathName's
parent must exist.
An entry is a widget that displays a one-line text string
Page 1 Plan 9 (printed 12/30/24)
ENTRY(9) ENTRY(9)
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 charac-
ters 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
Page 2 Plan 9 (printed 12/30/24)
ENTRY(9) ENTRY(9)
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.
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
Page 3 Plan 9 (printed 12/30/24)
ENTRY(9) ENTRY(9)
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 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
Page 4 Plan 9 (printed 12/30/24)
ENTRY(9) ENTRY(9)
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 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.
Page 5 Plan 9 (printed 12/30/24)
ENTRY(9) ENTRY(9)
[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.
[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
Page 6 Plan 9 (printed 12/30/24)
ENTRY(9) ENTRY(9)
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 behaviour of entries can be changed by defining new
bindings for individual widgets.
SEE ALSO
options(9), types(9)
Page 7 Plan 9 (printed 12/30/24)