ENTRY(9)ENTRY(9)NAMEentry - Create and manipulate entry widgets
SYNOPSISentry 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 exam‐
ple, 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 pathName argument)
and makes it into an entry widget. Additional 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 cre‐
ated, 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 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
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 operations 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 character in the entry's
string, in any of the following ways:
number Specifies the character as a numerical index, where 0 cor‐
responds 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 numeri‐
cal index equal to the length of the entry's string.
insert Indicates the character adjacent to and immediately follow‐
ing 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 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 character spanning that x-coordinate
is used. For example, ``@0'' indicates the left-most char‐
acter 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 widget. 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 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 indi‐
cated by index. Returns an empty string.
pathName see index
Adjusts the view in the window so that the character 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
currently in the entry, then a new selection is created
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 charac‐
ter 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 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 fol‐
lowing forms:
pathName xview
Returns a list containing two elements. Each element 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 ele‐
ment 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 win‐
dow.
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. 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 vis‐
ible.
DEFAULT BINDINGS
Tk automatically creates bindings for entries that give them the fol‐
lowing 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 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 cursor 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 selection, 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 inser‐
tion 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 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 ALSOoptions(9), types(9)ENTRY(9)
