Next / Previous / Contents / Shipman's homepage

24. The Text widget

Text widgets are a much more generalized method for handling multiple lines of text than the Label widget. Text widgets are pretty much a complete text editor in a window:

To create a text widget as the child of a root window or frame named parent:

    w = tk.Text(parent, option, ...)

The constructor returns the new Text widget. Options include:

Table 33. Text widget options

autoseparators If the undo option is set, the autoseparators option controls whether separators are automatically added to the undo stack after each insertion or deletion (if autoseparators=True) or not (if autoseparators=False). For an overview of the undo mechanism, see Section 24.7, “The Text widget undo/redo stack”.
bg or background The default background color of the text widget. See Section 5.3, “Colors”.
bd or borderwidth The width of the border around the text widget; see Section 5.1, “Dimensions”. The default is two pixels.
cursor The cursor that will appear when the mouse is over the text widget. See Section 5.8, “Cursors”.
exportselection Normally, text selected within a text widget is exported to be the selection in the window manager. Set exportselection=0 if you don't want that behavior.
font The default font for text inserted into the widget. Note that you can have multiple fonts in the widgets by using tags to change the properties of some text. See Section 5.4, “Type fonts”.
fg or foreground The color used for text (and bitmaps) within the widget. You can change the color for tagged regions; this option is just the default.
height The height of the widget in lines (not pixels!), measured according to the current font size.
highlightbackground The color of the focus highlight when the text widget does not have focus. See Section 53, “Focus: routing keyboard input”.
highlightcolor The color of the focus highlight when the text widget has the focus.
highlightthickness The thickness of the focus highlight. Default is 1. Set highlightthickness=0 to suppress display of the focus highlight.
insertbackground The color of the insertion cursor. Default is black.
insertborderwidth Size of the 3-D border around the insertion cursor. Default is 0.
insertofftime The number of milliseconds the insertion cursor is off during its blink cycle. Set this option to zero to suppress blinking. Default is 300.
insertontime The number of milliseconds the insertion cursor is on during its blink cycle. Default is 600.
insertwidth Width of the insertion cursor (its height is determined by the tallest item in its line). Default is 2 pixels.
maxundo This option sets the maximum number of operations retained on the undo stack. For an overview of the undo mechanism, see Section 24.7, “The Text widget undo/redo stack”. Set this option to -1 to specify an unlimited number of entries in the undo stack.
padx The size of the internal padding added to the left and right of the text area. Default is one pixel. For possible values, see Section 5.1, “Dimensions”.
pady The size of the internal padding added above and below the text area. Default is one pixel.
relief The 3-D appearance of the text widget. Default is relief=tk.SUNKEN; for other values, see Section 5.6, “Relief styles”.
selectbackground The background color to use displaying selected text.
selectborderwidth The width of the border to use around selected text.
selectforeground The foreground color to use displaying selected text.
spacing1 This option specifies how much extra vertical space is put above each line of text. If a line wraps, this space is added only before the first line it occupies on the display. Default is 0.
spacing2 This option specifies how much extra vertical space to add between displayed lines of text when a logical line wraps. Default is 0.
spacing3 This option specifies how much extra vertical space is added below each line of text. If a line wraps, this space is added only after the last line it occupies on the display. Default is 0.
state Normally, text widgets respond to keyboard and mouse events; set state=tk.NORMAL to get this behavior. If you set state=tk.DISABLED, the text widget will not respond, and you won't be able to modify its contents programmatically either.
tabs This option controls how tab characters position text. See Section 24.6, “Setting tabs in a Text widget”.
takefocus Normally, focus will visit a text widget (see Section 53, “Focus: routing keyboard input”). Set takefocus=0 if you do not want focus in the widget.
undo Set this option to True to enable the undo mechanism, or False to disable it. See Section 24.7, “The Text widget undo/redo stack”.
width The width of the widget in characters (not pixels!), measured according to the current font size.
wrap This option controls the display of lines that are too wide.
  • With the default behavior, wrap=tk.CHAR, any line that gets too long will be broken at any character.

  • Set wrap=tk.WORD and it will break the line after the last word that will fit.

  • If you want to be able to create lines that are too long to fit in the window, set wrap=tk.NONE and provide a horizontal scrollbar.

xscrollcommand To make the text widget horizontally scrollable, set this option to the .set method of the horizontal scrollbar.
yscrollcommand To make the text widget vertically scrollable, set this option to the .set method of the vertical scrollbar.

24.1. Text widget indices

An index is a general method of specifying a position in the content of a text widget. An index is a string with one of these forms:

'line.column'

The position just before the given column (counting from zero) on the given line (counting from one). Examples: '1.0' is the position of the beginning of the text; '2.3' is the position before the fourth character of the second line.

'line.end'

The position just before the newline at the end of the given line (counting from one). So, for example, index '10.end' is the position at the end of the tenth line.

tk.INSERT

The position of the insertion cursor in the text widget. This constant is equal to the string 'insert'.

tk.CURRENT

The position of the character closest to the mouse pointer. This constant is equal to the string 'current'.

tk.END

The position after the last character of the text. This constant is equal to the string 'end'.

tk.SEL_FIRST

If some of the text in the widget is currently selection (as by dragging the mouse over it), this is the position before the start of the selection. If you try to use this index and nothing is selected, a tk.TclError exception will be raised. This constant is equal to the string 'sel.first'.

tk.SEL_LAST

The position after the end of the selection, if any. As with SEL_FIRST, you'll get a tk.TclError exception if you use such an index and there is no selection. This constant is equal to the string 'sel.last'.

'markname'

You can use a mark as an index; just pass its name where an index is expected. See Section 24.2, “Text widget marks”.

'tag.first'

The position before the first character of the region tagged with name tag; see Section 24.5, “Text widget tags”.

'tag.last'

The position after the last character of a tagged region.

'@x,y'

The position before the character closest to the coordinate (x, y).

embedded-object

If you have an image or window embedded in the text widget, you can use the PhotoImage, BitmapImage, or embedded widget as an index. See Section 24.3, “Text widget images” and Section 24.4, “Text widget windows”.

In addition to the basic index options above, you can build arbitrary complex expressions by adding any of these suffixes to a basic index or index expression:

+ n chars

From the given index, move forward n characters. This operation will cross line boundaries.

For example, suppose the first line looks like this:

abcdef

The index expression “1.0 + 5 chars” refers to the position between e and f. You can omit blanks and abbreviate keywords in these expressions if the result is unambiguous. This example could be abbreviated “1.0+5c”.

- n chars

Similar to the previous form, but the position moves backwards n characters.

+ n lines

Moves n lines past the given index. Tkinter tries to leave the new position in the same column as it was on the line it left, but if the line at the new position is shorter, the new position will be at the end of the line.

- n lines

Moves n lines before the given index.

linestart

Moves to the position before the first character of the given index. For example, position “current linestart” refers to the beginning of the line closest to the mouse pointer.

lineend

Moves to the position after the last character of the given index. For example, position “sel.last lineend” refers to the end of the line containing the end of the current selection.

wordstart

The position before the beginning of the word containing the given index. For example, index “11.44 wordstart” refers to the position before the word containing position 44 on line 11.

For the purposes of this operation, a word is either a string of consecutive letter, digit, or underbar (_) characters, or a single character that is none of these types.