This is an unofficial mirror of Tkinter reference documentation (based on Python 2.7 and Tk 8.5) created by the late John Shipman.
It was last updated in 2013 and is unmaintained. [More info]
The purpose of an Entry
widget is to let the
user see and modify a single line of
text.
If you want to display multiple
lines of text that can be edited, see Section 24, “The Text
widget”.
If you want to display one or more lines of text that
cannot be modified by the user,
see Section 12, “The Label
widget”.
Some definitions:
The selection is a highlighted
region of the text in an Entry
widget,
if there is one.
Typically the selection is made by the user with the
mouse, and selected text is copied to the system's
clipboard. However, Tkinter allows you to control
whether or not selected text gets copied to the
clipboard. You can also select text in an Entry
under program control.
The insertion cursor shows where new text will be inserted. It is displayed only when the user clicks the mouse somewhere in the widget. It usually appears as a blinking vertical line inside the widget. You can customize its appearance in several ways.
Positions within the widget's displayed text are given as an index. There are several ways to specify an index:
As normal Python indexes, starting from 0.
The constant tk.END
refers to the
position after the existing text.
The constant tk.INSERT
refers to the
current position of the insertion cursor.
The constant tk.ANCHOR
refers to the
first character of the selection, if there is a
selection.
You may need to figure out which character position
in the widget corresponds to a given mouse
position. To simplify that process, you can use as
an index a string of the form '@
, where
n
'
is the
horizontal distance in pixels between the left edge
of the n
Entry
widget and the mouse.
Such an index will specify the character at that
horizontal mouse position.
To create a new Entry
widget in a root
window or frame named
:
parent
w
= tk.Entry(parent
,option
, ...)
This constructor returns the new Entry
widget. Options include:
Table 17. Entry
widget options
bg or background | The background color inside the entry area. Default is a light gray. |
bd or
borderwidth | The width of the border around the entry area; see Section 5.1, “Dimensions”. The default is two pixels. |
cursor | The cursor used when the mouse is within the entry widget; see Section 5.8, “Cursors”. |
disabledbackground
|
The background color to be displayed when the
widget is in the tk.DISABLED state.
For option values, see bg above.
|
disabledforeground
|
The foreground color to be displayed when the
widget is in the tk.DISABLED state.
For option values, see fg below.
|
exportselection
|
By default, if you select text within an Entry widget, it is automatically exported
to the clipboard. To avoid this exportation, use
exportselection=0 .
|
fg or foreground | The color used to render the text. Default is black. |
font | The font used for text entered in the widget by the user. See Section 5.4, “Type fonts”. |
highlightbackground | Color of the focus highlight when the widget does not have focus. See Section 53, “Focus: routing keyboard input”. |
highlightcolor | Color shown in the focus highlight when the widget has the focus. |
highlightthickness | Thickness of the focus highlight. |
insertbackground |
By default, the insertion cursor (which shows the
point within the text where new keyboard input will
be inserted) is black. To get a different color of
insertion cursor, set insertbackground to any color; see Section 5.3, “Colors”.
|
insertborderwidth |
By default, the insertion cursor is a simple
rectangle. You can get the cursor with the tk.RAISED relief effect (see Section 5.6, “Relief styles”) by setting insertborderwidth to the dimension of the 3-d
border. If you do, make sure that the insertwidth option is at least twice
that value.
|
insertofftime |
By default, the insertion cursor blinks. You can
set insertofftime to a value in
milliseconds to specify how much time the insertion
cursor spends off. Default is 300. If you use
insertofftime=0 , the insertion
cursor won't blink at all.
|
insertontime |
Similar to insertofftime , this
option specifies how much time the cursor spends
on per blink. Default is 600 (milliseconds).
|
insertwidth |
By default, the insertion cursor is 2 pixels wide.
You can adjust this by setting insertwidth to any dimension.
|
justify |
This option controls how the text is justified when
the text doesn't fill the widget's width. The
value can be tk.LEFT (the default),
tk.CENTER , or tk.RIGHT .
|
readonlybackground
|
The background color to be displayed when the
widget's state option is 'readonly' .
|
relief |
Selects three-dimensional shading effects around
the text entry. See Section 5.6, “Relief styles”. The
default is relief=tk.SUNKEN .
|
selectbackground | The background color to use displaying selected text. See Section 5.3, “Colors”. |
selectborderwidth | The width of the border to use around selected text. The default is one pixel. |
selectforeground | The foreground (text) color of selected text. |
show |
Normally, the characters that the user types appear
in the entry. To make a “password”
entry that echoes each character as an asterisk,
set show='*' .
|
state |
Use this option to disable the Entry widget so that the user can't type
anything into it. Use state=tk.DISABLED to disable the widget, state=tk.NORMAL to allow user input again. Your program can also
find out whether the cursor is currently over the
widget by interrogating this option; it will
have the value tk.ACTIVE when the mouse
is over it. You can also set this option to 'disabled' , which is like the tk.DISABLED state, but the contents of the
widget can still be selected or copied.
|
takefocus | By default, the focus will tab through entry widgets. Set this option to 0 to take the widget out of the sequence. For a discussion of focus, see Section 53, “Focus: routing keyboard input”. |
textvariable |
In order to be able to retrieve the current text
from your entry widget, you must set this option to
an instance of the StringVar class;
see Section 52, “Control variables: the values behind the widgets”. You can
retrieve the text using , or set
it using , where
is the
associated control variable.
|
validate
|
You can use this option to set up the widget so that
its contents are checked by a validation function at
certain times. See Section 10.2, “Adding validation to an |
validatecommand
|
A callback that validates the text of the widget.
See Section 10.2, “Adding validation to an Entry
widget”.
|
width |
The size of the entry in characters. The default is
20. For proportional fonts, the physical length of
the widget will be based on the average width of a
character times the value of the width option.
|
xscrollcommand |
If you expect that users will often enter more text
than the onscreen size of the widget, you can link
your entry widget to a scrollbar. Set this option
to the .set method of the scrollbar.
For more information, see Section 10.1, “Scrolling an Entry widget”.
|
Methods on Entry
objects include:
.delete(first
,
last
=None)
Deletes characters from the widget, starting with the
one at index
, up to but
not including the character at
position first
. If the second argument is omitted, only the
single character at position last
is deleted.
first
.get()
Returns the entry's current text as a string.
.icursor(index
)
Set the insertion cursor just before the character at
the given
.
index
.index(index
)
Shift the contents of the entry so that the character
at the given
is
the leftmost visible character. Has no effect if the
text fits entirely within the entry.
index
.insert(index
,
s
)
Inserts string
before the
character at the given s
.
index
.scan_dragto(x
)
See the scan_mark
method below.
.scan_mark(x
)
Use this option to set up fast scanning of the
contents of the Entry
widget that has
a scrollbar that supports horizontal scrolling.
To implement this feature, bind the mouse's
button-down event to a handler that calls scan_mark(
,
where x
)
is the current mouse x
position. Then bind the
x
<Motion>
event to a handler that
calls scan_dragto(
, where x
)
is the current mouse x
position. The x
scan_dragto
method scrolls the contents of
the Entry
widget continuously at a
rate proportional to the horizontal distance between
the position at the time of the scan_mark
call and the current position.
.select_adjust(index
)
This method is used to make sure that the selection includes
the character at the specified
. If the
selection already includes that character, nothing
happens. If not, the selection is expanded from its
current position (if any) to include position index
.
index
.select_clear()
Clears the selection. If there isn't currently a selection, has no effect.
.select_from(index
)
Sets the tk.ANCHOR
index position to the
character selected by
, and
selects that character.
index
.select_present()
If there is a selection, returns true, else returns false.
.select_range(start
, end
)
Sets the selection under
program control. Selects the text starting at the
start
, up to but
not including the character at
the index
index. The end
position
must be before the start
position.
end
To select all the text in an entry widget e
, use e.select_range(0, tk.END)
.
.select_to(index
)
Selects all the text from the tk.ANCHOR
position up to but not including the character at the
given
.
index
.xview(index
)
Same as .xview()
. This method is
useful in linking the Entry
widget to
a horizontal scrollbar. See Section 10.1, “Scrolling an Entry
widget”.
.xview_moveto(f
)
Positions the text in the entry so that the character
at position
, relative to the entire text, is positioned at the
left edge of the window. The f
argument must
be in the range [0,1], where 0 means the left end of
the text and 1 the right end.
f
.xview_scroll(number
, what
)
Used to scroll the entry horizontally. The
argument
must be either what
tk.UNITS
, to scroll by
character widths, or tk.PAGES
, to scroll
by chunks the size of the entry widget. The
is
positive to scroll left to right, negative to scroll
right to left. For example, for an entry widget
number
e
, e.xview_scroll(-1,
tk.PAGES)
would move the text one
“page” to the right, and e.xview_scroll(4, tk.UNITS)
would move the text
four characters to the left.