8. The Entry widget

8. The `Entry` widget

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 17, “The Text widget”.
If you want to display one or more lines of text that cannot be modified by the user, see Section 10, “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 END refers to the position after the existing text.
- The constant INSERT refers to the current position of the insertion cursor.
- The constant 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 "@n", where n is the horizontal distance in pixels between the left edge of the 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 master:

    w = Entry ( master, option, ... )

This constructor returns the entry widget object. Options include:

`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. Default is 2.
`cursor`	The cursor used when the mouse is within the entry widget; see Section 4.8, “Cursors”.
`font`	The font used for text entered in the widget by the user. See Section 4.4, “Type fonts”.
`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.
`highlightbackground`	Color of the focus highlight when the widget does not have focus. See Section 23, “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 4.3, “Colors”.
`insertborderwidth`	By default, the insertion cursor is a simple rectangle. You can get the cursor with the `RAISED` relief effect (see Section 4.6, “Relief styles”) by setting `insertborderwidth` to the dimension of the 3-d border. If you do, make sure that the `insertwidth` attribute 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 attribute 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 `LEFT` (the default), `CENTER`, or `RIGHT`.
`relief`	Selects three-dimensional shading effects around the text entry. See Section 4.6, “Relief styles”. The default is `relief=SUNKEN`.
`selectbackground`	The background color to use displaying selected text. See Section 4.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 attribute to disable the `Entry` widget so that the user can't type anything into it. Use `state=DISABLED` to disable the widget, `state=NORMAL` to allow user input again. Your program can also find out whether the cursor is currently over the widget by interrogating this attribute; it will have the value `ACTIVE` when the mouse is over it.
`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 23, “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 22, “Control variables: the values behind the widgets”. You can retrieve the text using `v.get()`, or set it using `v.set()`, where `v` is the associated control variable.
`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 8.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 first, up to but not including the character at position last. If the second argument is omitted, only the single character at position first is deleted.

.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 index is the leftmost visible character. Has no effect if the text fits entirely within the entry.

.insert ( index, s )

Inserts string s before the character at the given index.

.select_adjust ( index )

This method is used to make sure that the selection includes the character at the specified index. 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.

.select_clear()

Clears the selection. If there isn't currently a selection, has no effect.

.select_from ( index )

Sets the ANCHOR index position to the character selected by index, and selects that character.

.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 index, up to but not including the character at the end index. The start position must be before the end position.

To select all the text in an entry widget e, use e.select_range(0, END).

.select_to ( index )

Selects all the text from the 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 8.1, “Scrolling an Entry widget”.

.xview_moveto ( f )

Positions the text in the entry so that the character at position f, 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.

.xview_scroll ( number, what )

Used to scroll the entry horizontally. The what argument must be either UNITS, to scroll by character widths, or PAGES, to scroll by chunks the size of the entry widget. The number is positive to scroll left to right, negative to scroll right to left. For example, for an entry widget e, e.xview_scroll(-1, PAGES) would move the text one “page” to the right, and e.xview_scroll(4, UNITS) would move the text four characters to the left.

Tkinter reference: a GUI for Python

8. The Entry widget

8. The `Entry` widget