We're back after a server migration that caused effbot.org to fall over a bit harder than expected. Expect some glitches.

The Tkinter Entry Widget

The Entry widget is a standard Tkinter widget used to enter or display a single line of text.

When to use the Entry Widget

The entry widget is used to enter text strings. This widget allows the user to enter one line of text, in a single font.

To enter multiple lines of text, use the Text widget.

Patterns

To add entry text to the widget, use the insert method. To replace the current text, you can call delete before you insert the new text.

e = Entry(master)
e.pack()

e.delete(0, END)
e.insert(0, "a default value")

To fetch the current entry text, use the get method:

s = e.get()

You can also bind the entry widget to a StringVar instance, and set or get the entry text via that variable:

v = StringVar()
e = Entry(master, textvariable=v)
e.pack()

v.set("a default value")
s = v.get()

This example creates an Entry widget, and a Button that prints the current contents:

from Tkinter import *

master = Tk()

e = Entry(master)
e.pack()

e.focus_set()

def callback():
    print e.get()

b = Button(master, text="get", width=10, command=callback)
b.pack()

mainloop()


e = Entry(master, width=50)
e.pack()

text = e.get()
def makeentry(parent, caption, width=None, **options):
    Label(parent, text=caption).pack(side=LEFT)
    entry = Entry(parent, **options)
    if width:
        entry.config(width=width)
    entry.pack(side=LEFT)
    return entry

user = makeentry(parent, "User name:", 10)
password = makeentry(parent, "Password:", 10, show="*")
content = StringVar()
entry = Entry(parent, text=caption, textvariable=content)

text = content.get()
content.set(text)

FIXME: More patterns to be added.

In newer versions, the Entry widget supports custom events. Document them, and add examples showing how to bind them.

Add ValidateEntry subclass as an example?

Concepts

Indexes

The Entry widget allows you to specify character positions in a number of ways:

  • Numerical indexes
  • ANCHOR
  • END
  • INSERT
  • Mouse coordinates (“@x”)

Numerical indexes work just like Python list indexes. The characters in the string are numbered from 0 and upwards. You specify ranges just like you slice lists in Python: for example, (0, 5) corresponds to the first five characters in the entry widget.

ANCHOR (or the string “anchor”) corresponds to the start of the selection, if any. You can use the select_from method to change this from the program.

END (or “end”) corresponds to the position just after the last character in the entry widget. The range (0, END) corresponds to all characters in the widget.

INSERT (or “insert”) corresponds to the current position of the text cursor. You can use the icursor method to change this from the program.

Finally, you can use the mouse position for the index, using the following syntax:

    "@%d" % x

where x is given in pixels relative to the left edge of the entry widget.

Reference

Entry(master=None, **options) (class) [#]

A text entry field.

master
Parent widget.
**options
Widget options. See the description of the config method for a list of available options.

config(**options) [#]

Modifies one or more widget options. If no options are given, the method returns a dictionary containing all current option values.

**options
Widget options.
background=
Widget background. The default is system specific. (the option database name is background, the class is Background)
bg=
Same as background.
borderwidth=
Border width. The default is system specific, but is usually a few pixels. (borderWidth/BorderWidth)
bd=
Same as borderwidth.
cursor=
Widget cursor. The default is a text insertion cursor (typically an “I-beam” cursor, e.g. xterm). (cursor/Cursor)
disabledbackground=
Background to use when the widget is disabled. If omitted or blank, the standard background is used instead. (disabledBackground/DisabledBackground)
disabledforeground=
Text color to use when the widget is disabled. If omitted or blank, the standard foreground is used instead. (disabledForeground/DisabledForeground)
exportselection=
If true, selected text is automatically exported to the clipboard. Default is true. (exportSelection/ExportSelection)
font=
Widget font. The default is system specific. (font/Font)
foreground=
Text color. (foreground/Foreground)
fg=
Same as foreground.
highlightbackground=
Together with highlightcolor, this option controls how to draw the focus highlight border. This option is used when the widget doesn’t have focus. The default is system specific. (highlightBackground/HighlightBackground)
highlightcolor=
Same as highlightbackground, but is used when the widget has focus. (highlightColor/HighlightColor)
highlightthickness=
The width of the focus highlight border. Default is typically a few pixels, unless the system indicates focus by modifying the button itself (like on Windows). (highlightThickness/HighlightThickness)
insertbackground=
Color used for the insertion cursor. (insertBackground/Foreground)
insertborderwidth=
Width of the insertion cursor’s border. If this is set to a non-zero value, the cursor is drawn using the RAISED border style. (insertBorderWidth/BorderWidth)
insertofftime=
Together with insertontime, this option controls cursor blinking. Both values are given in milliseconds. (insertOffTime/OffTime)
insertontime=
See insertofftime. (insertOnTime/OnTime)
insertwidth=
Width of the insertion cursor. Usually one or two pixels. (insertWidth/InsertWidth)
invalidcommand=
FIXME. No default. (invalidCommand/InvalidCommand)
invcmd=
Same as invalidcommand.
justify=
How to align the text inside the entry field. Use one of LEFT, CENTER, or RIGHT. The default is LEFT. (justify/Justify)
readonlybackground=
The background color to use when the state is “readonly”. If omitted or blank, the standard background is used instead. (readonlyBackground/ReadonlyBackground)
relief=
Border style. The default is SUNKEN. Other possible values are FLAT, RAISED, GROOVE, and RIDGE. (relief/Relief)
selectbackground=
Selection background color. The default is system and display specific. (selectBackground/Foreground)
selectborderwidth=
Selection border width. The default is system specific. (selectBorderWidth/BorderWidth)te
selectforeground=
Selection text color. The default is system specific. (selectForeground/Background)
show=
Controls how to display the contents of the widget. If non-empty, the widget displays a string of characters instead of the actual contents. To get a password entry widget, set this option to “*”. (show/Show)
state=
The entry state: NORMAL, DISABLED, or “readonly” (same as DISABLED, but contents can still be selected and copied). Default is NORMAL. Note that if you set this to DISABLED or “readonly”, calls to insert and delete are ignored. (state/State)
takefocus=
Indicates that the user can use the Tab key to move to this widget. Default is an empty string, which means that the entry widget accepts focus only if it has any keyboard bindings (default is on, in other words). (takeFocus/TakeFocus)
textvariable=
Associates a Tkinter variable (usually a StringVar) to the contents of the entry field. (textVariable/Variable)
validate=
Specifies when validation should be done. You can use “focus” to validate whenever the widget gets or loses the focus, “focusin” to validate only when it gets focus, “focusout” to validate when it loses focus, “key” on any modification, and ALL for all situations. Default is NONE (no validation). (validate/Validate)
validatecommand=
A function or method to call to check if the contents is valid. The function should return a true value if the new contents is valid, or false if it isn’t. Note that this option is only used if the validate option is not NONE. (validateCommand/ValidateCommand)
vcmd=
Same as validatecommand.
width=
Width of the entry field, in character units. Note that this controlS the size on screen; it does not limit the number of characters that can be typed into the entry field. The default width is 20 character. (width/Width)
xscrollcommand=
Used to connect an entry field to a horizontal scrollbar. This option should be set to the set method of the corresponding scrollbar. (xScrollCommand/ScrollCommand)

delete(first, last=None) [#]

Deletes the character at index, or within the given range. Use delete(0, END) to delete all text in the widget.

first
Start of range.
last
Optional end of range. If omitted, only a single character is removed.

get() [#]

Gets the current contents of the entry field.

Returns:
The widget contents, as a string.

icursor(index) [#]

Moves the insertion cursor to the given index. This also sets the INSERT index.

index
Where to move the cursor.

index(index) [#]

Gets the numerical position corresponding to the given index.

index
An index.
Returns:
The corresponding numerical index.

insert(index, string) [#]

Inserts text at the given index. Use insert(INSERT, text) to insert text at the cursor, insert(END, text) to append text to the widget.

index
Where to insert the text.
string
The text to insert.

scan_dragto(x) [#]

Sets the scanning anchor for fast horizontal scrolling to the given mouse coordinate.

x
Current horizontal mouse position.

scan_mark(x) [#]

Scrolls the widget contents sideways according to the given mouse coordinate. The text is moved 10 times the distance between the scanning anchor and the new position.

x
Current horizontal mouse position.

select_adjust(index) [#]

Same as selection_adjust.

select_clear() [#]

Same as selection_clear.

select_from(index) [#]

Same as selection_from.

select_present() [#]

Same as selection_present.

select_range(start, end) [#]

Same as selection_range.

select_to(index) [#]

Same as selection_to.

selection_adjust(index) [#]

Adjusts the selection to include also the given character. If index is already selected, do nothing.

index
The index.

selection_clear() [#]

Clears the selection.

selection_from(index) [#]

Starts a new selection. This also sets the ANCHOR index.

index
The index.

selection_present() [#]

Checks if text is selected.

Returns:
A true value if some part of the text is selected.

selection_range(start, end) [#]

Explicitly sets the selection range. Start must be smaller than end. Use selection_range(0, END) to select all text in the widget.

start
Start of selection range.
end
End of range.

selection_to(index) [#]

Selects all text between ANCHOR and the given index.

index

xview(index) [#]

Makes sure the given index is visible. The entry view is scrolled if necessary.

index
An index.

xview_moveto(fraction) [#]

Adjusts the entry view so that the given offset is at the left edge of the canvas. Offset 0.0 is the beginning of the entry string, 1.0 the end.

fraction

xview_scroll(number, what) [#]

Scrolls the entry view horizontally by the given amount.

number
Number of units.
what
What unit to use. This can be either “units” (characters) or “pages” (larger steps).