Tkinter > le texte et les Labels

Label

Pour afficher du texte ou des images. Une seule police, mais avec des span.

Labels are used to display texts and images. The label widget uses double buffering, so you can update the contents at any time, without annoying flicker.

To display data that the user can manipulate in place, it’s probably easier to use the Canvas widget.

Label(fenêtre,options)

Patterns

To use a label, you just have to specify what to display in it (this can be text, a bitmap, or an image):

 

master = Tk()
w = Label(master, text="coucou")
w.pack()
mainloop()

 

If you don’t specify a size, the label is made just large enough to hold its contents. You can also use the height and width options to explicitly set the size. If you display text in the label, these options define the size of the label in text units. If you display bitmaps or images instead, they define the size in pixels (or other screen units). See the Button description for an example how to specify the size in pixels also for text labels.

You can specify which color to use for the label with the foreground (or fg) and background (or bg) options. You can also choose which font to use in the label (the following example uses Tk 8.0 font descriptors). Use colors and fonts sparingly; unless you have a good reason to do otherwise, you should stick to the default values.

 

w = Label(master, text="Rouge", fg="red")
w = Label(master, text="Helvetica", font=("Helvetica", 16))

 

Labels can display multiple lines of text. You can use newlines or use the wraplength option to make the label wrap text by itself. When wrapping text, you might wish to use the anchor and justify options to make things look exactly as you wish. An example:

 

w = Label(master, text=longtext, anchor=W, justify=LEFT)

 

You can associate a Tkinter variable with a label. When the contents of the variable changes, the label is automatically updated:

 

v = StringVar()
Label(master, textvariable=v).pack()

v.set("New Text!")

 

You can use the label to display PhotoImage and BitmapImage objects. When doing this, make sure you keep a reference to the image object, to prevent it from being garbage collected by Python’s memory allocator. You can use a global variable or an instance attribute, or easier, just add an attribute to the widget instance:

 

photo = PhotoImage(file="icon.gif")
w = Label(parent, image=photo)
w.photo = photo
w.pack()

Reference

config(**options)

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

activebackground= What background color to use when the label is active (set with the state option). The default is platform specific. (the option database name is activeBackground, the class is Foreground)

activeforeground= What foreground color to use when the label is active. The default is platform specific. (activeForeground/Background)

anchor= Controls where in the label the text (or image) should be located. Use one of N, NE, E, SE, S, SW, W, NW, or CENTER. Default is CENTER. (anchor/Anchor)

bg= background.

bitmap= The bitmap to display in the widget. If the image option is given, this option is ignored. (bitmap/Bitmap)

bd= borderwidth.

compound= Controls how to combine text and image in the label. By default, if an image or bitmap is given, it is drawn instead of the text. If this option is set to CENTER, the text is drawn on top of the image. If this option is set to one of BOTTOM, LEFT, RIGHT, or TOP, the image is drawn besides the text (use BOTTOM to draw the image under the text, etc.). Default is NONE. (compound/Compound)

cursor= What cursor to show when the mouse is moved over the label. The default is to use the standard cursor. (cursor/Cursor)

disabledforeground= What foreground color to use when the label is disabled. The default is system specific. (disabledForeground/DisabledForeground)

font= The font to use in the label. The label can only contain text in single font. The default is system specific. (font/Font)

fg= Same as foreground.

height= The height of the label. If the label displays text, the size is given in text units. If the label displays an image, the size is given in pixels (or screen units). If the size is set to 0, or omitted, it is calculated based on the label contents. (height/Height)

highlightbackground= What color to use for the highlight border when the widget does not have focus. The default is system specific, but usually the same as the standard background color. (highlightBackground/HighlightBackground)

highlightcolor= What color to use for the highlight border when the widget has focus. The default is system specific. (highlightColor/HighlightColor)

highlightthickness= The width of the highlight border. The default is 0 (no highlight border). (highlightThickness/HighlightThickness)

image= The image to display in the widget. The value should be a PhotoImage, BitmapImage, or a compatible object. If specified, this takes precedence over the text and bitmap options. (image/Image)

justify= Defines how to align multiple lines of text. Use LEFT, RIGHT, or CENTER. Note that to position the text inside the widget, use the anchor option. Default is CENTER. (justify/Justify)

padx= Extra horizontal padding to add around the text. The default is 1 pixel. (padX/Pad)

pady= Extra vertical padding to add around the text. The default is 1 pixel. (padY/Pad)

relief= Border decoration. The default is FLAT. Other possible values are SUNKEN, RAISED, GROOVE, and RIDGE. (relief/Relief)

state= Label state. This option controls how the label is rendered. The default is NORMAL. Other possible values are ACTIVE and DISABLED. (state/State)

takefocus= If true, the widget accepts input focus. The default is false. (takeFocus/TakeFocus)

text= The text to display in the label. The text can contain newlines. If the bitmap or image options are used, this option is ignored. (text/Text)

textvariable= Associates a Tkinter variable (usually a StringVar) with the label. If the variable is changed, the label text is updated. (textVariable/Variable)

underline= Used with the text option to indicate that a character should be underlined (e.g. for keyboard shortcuts). Default is -1 (no underline). (underline/Underline)

width= The width of the label. If the label displays text, the size is given in text units. If the label displays an image, the size is given in pixels (or screen units). If the size is set to 0, or omitted, it is calculated based on the label contents. (width/Width)

wraplength= Determines when a label’s text should be wrapped into multiple lines. This is given in screen units. Default is 0 (no wrapping). (wrapLength/WrapLength)

—

 

LabelFrame Widget

(new in Tk 8.4) The LabelFrame widget is a variant of the Tkinter Frame widget. By default, it draws a border around its child widgets, and it can also display a title.

When to use the LabelFrame Widget

The LabelFrame can be used when you want to group a number of related widgets, such as a number of radiobuttons.

Patterns #

To display a group, create a LabelFrame, and add child widgets to the frame as usual. The widget draws a border around the children, and a text label above them.

from Tkinter import *

master = Tk()

group = LabelFrame(master, text="Group", padx=5, pady=5)
group.pack(padx=10, pady=10)

w = Entry(group)
w.pack()

mainloop()

You can use options to control where and how to draw the label, and how to draw the border. See below for details.

Reference #

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

A frame widget with an internal group border and an opertional label.

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=

The background color to use in this frame. This defaults to the application background color. To prevent updates, set the color to an empty string. (the option database name is background, the class is Background)

bd=

Same as borderwidth.

bg=

Same as background.

borderwidth=

Border width. Defaults to 2 pixels. (borderWidth/BorderWidth)

class=

Default is Labelframe. (class/Class)

colormap=

Some displays support only 256 colors (some use even less). Such displays usually provide a color map to specify which 256 colors to use. This option allows you to specify which color map to use for this frame, and its child widgets.
By default, a new frame uses the same color map as its parent. Using this option, you can reuse the color map of another window instead (this window must be on the same screen and have the same visual characteristics). You can also use the value “new” to allocate a new color map for this frame.
You cannot change this option once you’ve created the frame. (colormap/Colormap)

container=

If true, this frame is a container widget. Defaults to false.
You cannot change this option once you’ve created the frame. (container/Container)

cursor=

The cursor to show when the mouse pointer is placed over this widget. Default is a system specific arrow cursor. (cursor/Cursor)

fg=

Same as foreground.

font=

Font to use for the label text. The default is system specific. (font/Font)

foreground=

Color to use for the label text. The default is system specific. (foreground/Foreground)

height=

Frame height, in pixels. No default value. (height/Height)

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. The default is typically a few pixels. (highlightThickness/HighlightThickness)

labelanchor=

Where to draw the label text. Default is NW (upper left corner). (labelAnchor/LabelAnchor)

labelwidget=

Widget to use for the label. If omitted, the frame uses the text option. No default value. (labelWidget/LabelWidget)

padx=

Horizontal internal padding. Default is 0. (padX/Pad)

pady=

Vertical internal padding. Default is 0. (padY/Pad)

relief=

Border style. The default is GROOVE. Other possible values are FLAT, RAISED, SUNKEN, and RIDGE. (relief/Relief)

takefocus=

If true, indicates that the user can use the Tab key to move to this widget. Default is 0 (false). (takeFocus/TakeFocus)

text=

The label text. (text/Text)

visual=

Screen visual. No default value. (visual/Visual)

width=

Frame width. No default value. (width/Width)

—

 

Message Widget

The Message widget is a variant of the Label, designed to display multiline messages. The message widget can wrap text, and adjust its width to maintain a given aspect ratio.

When to use the Message Widget

The widget can be used to display short text messages, using a single font. You can often use a plain Label instead. If you need to display text in multiple fonts, use a Text widget.

Patterns #

To create a message, all you have to do is to pass in a text string. The widget will automatically break the lines, if necessary.

from Tkinter import *

master = Tk()

w = Message(master, text="this is a message")
w.pack()

mainloop()

If you don’t specify anything else, the widget attepts to format the text to keep a given aspect ratio. If you don’t want that behaviour, you can specify a width:

w = Message(master, text="this is a relatively long message", width=50)
w.pack()

Reference #

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

A multi-line text message.

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.

anchor=

Where in the message widget the text should be placed. Use one of N, NE, E, SE, S, SW, W, NW, or CENTER. Default is CENTER. (the database name is anchor, the class is Anchor)

aspect=

Aspect ratio, given as the width/height relation in percent. The default is 150, which means that the message will be 50% wider than it is high. Note that if the width is explicitly set, this option is ignored. (aspect/Aspect)

background=

Message background color. The default value is system specific. (background/Background)

bg=

Same as background.

borderwidth=

Border width. Default value is 2. (borderWidth/BorderWidth)

bd=

Same as borderwidth.

cursor=

What cursor to show when the mouse is moved over the message widget. The default is to use the standard cursor. (cursor/Cursor)

font=

Message font. The default value is system specific. (font/Font)

foreground=

Text color. The default value is system specific. (foreground/Foreground)

fg=

Same as foreground.

highlightbackground=

Together with highlightcolor and highlightthickness, this option controls how to draw the highlight region. (highlightBackground/HighlightBackground)

highlightcolor=

See highlightbackground. (highlightColor/HighlightColor)

highlightthickness=

See highlightbackground. (highlightThickness/HighlightThickness)

justify=

Defines how to align multiple lines of text. Use LEFT, RIGHT, or CENTER. Note that to position the text inside the widget, use the anchor option. Default is LEFT. (justify/Justify)

padx=

Horizontal padding. Default is -1 (no padding). (padX/Pad)

pady=

Vertical padding. Default is -1 (no padding). (padY/Pad)

relief=

Border decoration. The default is FLAT. Other possible values are SUNKEN, RAISED, GROOVE, and RIDGE. (relief/Relief)

takefocus=

If true, the widget accepts input focus. The default is false. (takeFocus/TakeFocus)

text=

Message text. The widget inserts line breaks if necessary to get the requested aspect ratio. (text/Text)

textvariable=

Associates a Tkinter variable (usually a StringVar) with the message. If the variable is changed, the message text is updated. (textVariable/Variable)

width=

Widget width, in character units. If omitted, the widget picks a suitable width based on the aspect setting. (width/Width)

 

—

 

Text Widget

The Text widget provides formatted text display. It allows you to display and edit text with various styles and attributes. The widget also supports embedded images and windows.

When to use the Text Widget

The text widget is used to display text documents, containing either plain text or formatted text (using different fonts, embedded images, and other embellishments). The text widget can also be used as a text editor.

Concepts

The text widget stores and displays lines of text.

The text body can consist of characters, marks, and embedded windows or images. Different regions can be displayed in different styles, and you can also attach event bindings to regions.

By default, you can edit the text widget’s contents using the standard keyboard and mouse bindings. To disable editing, set the state option to DISABLED (but if you do that, you’ll also disable the insert and delete methods).

Indexes

Indexes are used to point to positions within the text handled by the text widget. Like Python sequence indexes, text widget indexes correspond to positions between the actual characters.

Tkinter provides a number of different index types:

line/column (“line.column”)

line end (“line.end”)

INSERT

CURRENT

END

user-defined marks

user-defined tags (“tag.first”, “tag.last”)

selection (SEL_FIRST, SEL_LAST)

window coordinate (“@x,y”)

embedded object name (window, images)

expressions

Lines and columns

line/column indexes are the basic index type. They are given as strings consisting of a line number and column number, separated by a period. Line numbers start at 1, while column numbers start at 0, like Python sequence indexes. You can construct indexes using the following syntax:

    "%d.%d" % (line, column)

It is not an error to specify line numbers beyond the last line, or column numbers beyond the last column on a line. Such numbers correspond to the line beyond the last, or the newline character ending a line.

Note that line/column indexes may look like floating point values, but it’s seldom possible to treat them as such (consider position 1.25 vs. 1.3, for example). I sometimes use 1.0 instead of “1.0” to save a few keystrokes when referring to the first character in the buffer, but that’s about it.

You can use the index method to convert all other kinds of indexes to the corresponding line/column index string.

Line endings

A line end index is given as a string consisting of a line number directly followed by the text “.end”. A line end index correspond to the newline character ending a line.

Named indexes

INSERT (or “insert”) corresponds to the insertion cursor.

CURRENT (or “current”) corresponds to the character closest to the mouse pointer. However, it is only updated if you move the mouse without holding down any buttons (if you do, it will not be updated until you release the button).

END (or “end”) corresponds to the position just after the last character in the buffer.

User-defined marks are named positions in the text. INSERT and CURRENT are predefined marks, but you can also create your own marks. See below for more information.

User-defined tags represent special event bindings and styles that can be assigned to ranges of text. For more information on tags, see below.

You can refer to the beginning of a tag range using the syntax “tag.first” (just before the first character in the text using that tag), and “tag.last” (just after the last character using that tag).

    "%s.first" % tagname
    "%s.last" % tagname

If the tag isn’t in use, Tkinter raises a TclError exception.

The selection is a special tag named SEL (or “sel”) that corresponds to the current selection. You can use the constants SEL_FIRST and SEL_LAST to refer to the selection. If there’s no selection, Tkinter raises a TclError exception.

Coordinates

You can also use window coordinates as indexes. For example, in an event binding, you can find the character closest to the mouse pointer using the following syntax:

    "@%d,%d" % (event.x, event.y)

Embedded objects

Embedded object name can be used to refer to windows and images embedded in the text widget. To refer to a window, simply use the corresponding Tkinter widget instance as an index. To refer to an embedded image, use the corresponding Tkinter PhotoImage or BitmapImage object.

Expressions

Expressions can be used to modify any kind of index. Expressions are formed by taking the string representation of an index (use str if the index isn’t already a string), and appending one or more modifiers from the following list:

“+ count chars” moves the index forward. The index will move over newlines, but not beyond the END index.

“- count chars” moves the index backwards. The index will move over newlines, but not beyond index “1.0”.

“+ count lines” and “- count lines” moves the index full lines forward (or backwards). If possible, the index is kept in the same column, but if the new line is too short, the index is moved to the end of that line.

“linestart” moves the index to the first position on the line.

“lineend” the index to the last position on the line (the newline, that is).

“wordstart” and “wordend” moves the index to the beginning (end) of the current word. Words are sequences of letters, digits, and underline, or single non-space characters.

The keywords can be abbreviated and spaces can be omitted as long as the result is not ambigous. For example, “+ 5 chars” can be shortened to “+5c”.

For compatibility with implementations where the constants are not ordinary strings, you may wish to use str or formatting operations to create the expression string. For example, here’s how to remove the character just before the insertion cursor:

    def backspace(event):
        event.widget.delete("%s-1c" % INSERT, INSERT)

Marks

Marks are (usually) invisible objects embedded in the text managed by the widget. Marks are positioned between character cells, and moves along with the text.

user-defined marks

INSERT

CURRENT

You can use any number of user-defined marks in a text widget. Mark names are ordinary strings, and they can contain anything except whitespace (for convenience, you should avoid names that can be confused with indexes, especially names containing periods). To create or move a mark, use the mark_set method.

Two marks are predefined by Tkinter, and have special meaning:

INSERT (or “insert”) is a special mark that is used to represent the insertion cursor. Tkinter draws the cursor at this mark’s position, so it isn’t entirely invisible.

CURRENT (or “current”) is a special mark that represents the character closest to the mouse pointer. However, it is only updated if you move the mouse without holding down any buttons (if you do, it will not be updated until you release the button).

Special marks can be manipulated as other user-defined marks, but they cannot be deleted.

If you insert or delete text before a mark, the mark is moved along with the other text. To remove a mark, you must use the mark_unset method. Deleting text around a mark doesn’t remove the mark itself.

If you insert text at a mark, it may be moved to the end of that text or left where it was, depending on the mark’s gravity setting (LEFT or RIGHT; default is RIGHT). You can use the mark_gravity method to change the gravity setting for a given mark.

In the following example, the “sentinel” mark is used to keep track of the original position for the insertion cursor.

    text.mark_set("sentinel", INSERT)
    text.mark_gravity("sentinel", LEFT)

You can now let the user enter text at the insertion cursor, and use text.get(sentinel, INSERT) to pick up the result.

Tags

Tags are used to associated a display style and/or event callbacks with ranges of text.

user-defined tags

SEL

You can define any number of user-defined tags. Any text range can have multiple tags, and the same tag can be used for many different ranges. Unlike the Canvas widget, tags defined for the text widget are not tightly bound to text ranges; the information associated with a tag is kept also if there is no text in the widget using it.

Tag names are ordinary strings, and they can contain anything except whitespace.

SEL (or “sel”) is a special tag which corresponds to the current selection, if any. There should be at most one range using the selection tag.

The following options are used with tag_config to specify the visual style for text using a certain tag.

background (color)

The background color to use for text having this tag.

Note that the bg alias cannot be used with tags; it is interpreted as bgstipple rather than background.

bgstipple (bitmap)

The name of a bitmap which is used as a stipple brush when drawing the background. Typical values are “gray12”, “gray25”, “gray50”, or “gray75”. Default is a solid brush (no bitmap).

borderwidth (distance)

The width of the text border. The default is 0 (no border).

Note that the bd alias cannot be used with tags.

fgstipple (bitmap)

The name of a bitmap which is used as a stipple brush when drawing the text. Typical values are “gray12”, “gray25”, “gray50”, or “gray75”. Default is a solid brush (no bitmap).

font (font)

The font to use for text having this tag.

foreground (color)

The color to use for text having this tag.

Note that the fg alias cannot be used with tags; it is interpreted as fgstipple rather than foreground.

justify (constant)

Controls text justification (the first character on a line determines how to justify the whole line). Use one of LEFT, RIGHT, or CENTER. Default is LEFT.

lmargin1 (distance)

The left margin to use for the first line in a block of text having this tag. Default is 0 (no left margin).

lmargin2 (distance)

The left margin to use for every line but the first in a block of text having this tag. Default is 0 (no left margin).

offset (distance)

Controls if the text should be offset from the baseline. Use a positive value for superscripts, a negative value for subscripts. Default is 0 (no offset).

overstrike (flag)

If non-zero, the text widget draws a line over the text that has this tag. For best results, you should use overstrike fonts instead.

relief (constant)

The border style to use for text having this tag. Use one of SUNKEN, RAISED, GROOVE, RIDGE, or FLAT. Default is FLAT (no border).

rmargin (distance)

The right margin to use for blocks of text having this tag. Default is 0 (no right margin).

spacing1 (distance)

Spacing to use above the first line in a block of text having this tag. Default is 0 (no extra spacing).

spacing2 (distance)

Spacing to use between the lines in a block of text having this tag. Default is 0 (no extra spacing).

spacing3 (distance)

Spacing to use after the last line of text in a block of text having this tag. Default is 0 (no extra spacing).

tabs (string)

underline (flag)

If non-zero, the text widget underlines the text that has this tag. For example, you can get the standard hyperlink look with (foreground=”blue”, underline=1). For best results, you should use underlined fonts instead.

wrap (constant)

The word wrap mode to use for text having this tag. Use one of NONE, CHAR, or WORD.

If you attach multiple tags to a range of text, style options from the most recently created tag override options from earlier tags. In the following example, the resulting text is blue on a yellow background.

    text.tag_config("n", background="yellow", foreground="red")
    text.tag_config("a", foreground="blue")
    text.insert(contents, ("n", "a"))

Note that it doesn’t matter in which order you attach tags to a range; it’s the tag creation order that counts.

You can change the tag priority using the tag_raise and tag_lower. If you add a text.tag_lower(“a”) to the above example, the text becomes red.

The tag_bind method allows you to add event bindings to text having a particular tag. Tags can generate mouse and keyboard events, plus Enter and Leave events. For example, the following code snippet creates a tag to use for any hypertext links in the text:

    text.tag_config("a", foreground="blue", underline=1)
    text.tag_bind("Enter>", show_hand_cursor)
    text.tag_bind("Leave>", show_arrow_cursor)
    text.tag_bind("Button-1>", click)
    text.config(cursor="arrow")

    text.insert(INSERT, "click here!", "a")

Patterns #

When you create a new text widget, it has no contents. To insert text into the widget, use the insert method and insert text at the INSERT or END indexes:

    text.insert(END, "hello, ")
    text.insert(END, "world")

You can use an optional third argument to the insert method to attach one or more tags to the newly inserted text:

    text.insert(END, "this is a ")
    text.insert(END, "link", ("a", "href"+href))

To insert embedded objects, use the window_create or image_create methods:

    button = Button(text, text="Click", command=click)
    text.window_create(INSERT, window=button)

To delete text, use the delete method. Here’s how to delete all text from the widget (this also deletes embedded windows and images, but not marks):

    text.delete(1.0, END)

To delete a single character (or an embedded window or image), you can use delete with only one argument:

    text.delete(INSERT)
    text.delete(button)

To make the widget read-only, you can change the state option from NORMAL to DISABLED:

    text.config(state=NORMAL)
    text.delete(1.0, END)
    text.insert(END, text)
    text.config(state=DISABLED)

Note that you must change the state back to NORMAL before you can modify the widget contents from within the program. Otherwise, calls to insert and delete will be silently ignored.

To fetch the text contents of the widget, use the get method:

    contents = text.get(1.0, END)

FIXME: add material on the dump method, and how to use it on 1.5.2 and earlier

Here’s a simple way to keep track of changes to the text widget:

    import md5
    def getsignature(contents):
        return md5.md5(contents).digest()

    text.insert(END, contents) # original contents
    signature = getsignature(contents)

    ...

    contents = text.get(1.0, END)
    if signature != getsignature(contents):
        print "contents have changed!"

FIXME: modify to handle ending linefeed added by text widget

The index method converts an index given in any of the supported formats to a line/column index. Use this if you need to store an “absolute” index.

    index = text.index(index)

However, if you need to keep track of positions in the text even after other text is inserted or deleted, you should use marks instead.

    text.mark_set("here", index)
    text.mark_unset("here")

The following function converts any kind of index to a (line, column)-tuple. Note that you can directly compare positions represented by such tuples.

    def getindex(text, index):
        return tuple(map(int, string.split(text.index(index), ".")))

    if getindex(text, INSERT)  getindex(text, "sentinel"):
        text.mark_set(INSERT, "sentinel")

The following example shows how to enumerate all regions in the text that has a given tag.

    ranges = text.tag_ranges(tag)
    for i in range(0, len(ranges), 2):
        start = ranges[i]
        stop = ranges[i+1]
        print tag, repr(text.get(start, stop))

The search method allows you to search for text. You can search for an exact match (default), or use a Tcl-style regular expression (call with the regexp option set to true).

    text.insert(END, "hello, world")

    start = 1.0
    while 1:
        pos = text.search("o", start, stopindex=END)
        if not pos:
            break
        print pos
        start = pos + "+1c"

Given an empty text widget, the above example prints 1.4 and 1.8 before it stops. If you omit the stopindex option, the search wraps around if it reaches the end of the text.

To search backwards, set the backwards option to true (to find all occurences, start at END, set stopindex to 1.0 to avoid wrapping, and use “-1c” to move the start position).

Reference #

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

A display/editor widget for formatted text.

master

Parent widget.

**options

Widget options. See the description of the config method for a list of available options.

bbox(index) [#]

Calculates the bounding box for the given character.

This method only works if the text widget is updated. To make sure this is the case, you can call the update_idletasks method first.

index

Character index.

Returns:

A 4-tuple (x, y, width, height), or None, if the character is not visible.

compare(index1, op, index2) [#]

Compares two indexes. The op argument is one of “<”, “<=”, “==”, “>=”, “>”, or “!=” (Python’s “<>” syntax is not supported).

index1

First index.

op

Operator (see above).

index2

Second index.

Returns:

A true value if the condition is true.

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.

autoseparators=

Default is 1. (autoSeparators/AutoSeparators)

background=

Default value is system specific. (the database name is background, the class is Background)

bg=

Same as background.

borderwidth=

Default value is 2. (borderWidth/BorderWidth)

bd=

Same as borderwidth.

cursor=

Default value is “xterm”. (cursor/Cursor)

exportselection=

Default value is 1. (exportSelection/ExportSelection)

font=

Default value is system specific. (font/Font)

foreground=

Default value is system specific. (foreground/Foreground)

fg=

Same as foreground.

height=

Default value is 24. (height/Height)

highlightbackground=

Default value is system specific. (highlightBackground/HighlightBackground)

highlightcolor=

Default value is system specific. (highlightColor/HighlightColor)

highlightthickness=

Default value is 0. (highlightThickness/HighlightThickness)

insertbackground=

Default value is system specific. (insertBackground/Foreground)

insertborderwidth=

Default value is 0. (insertBorderWidth/BorderWidth)

insertofftime=

Default value is 300. (insertOffTime/OffTime)

insertontime=

Default value is 600. (insertOnTime/OnTime)

insertwidth=

Default value is 2. (insertWidth/InsertWidth)

maxundo=

Default is 0. (maxUndo/MaxUndo)

padx=

Default value is 1. (padX/Pad)

pady=

Default value is 1. (padY/Pad)

relief=

Default value is SUNKEN. (relief/Relief)

selectbackground=

Default value is system specific. (selectBackground/Foreground)

selectborderwidth=

Default value is 0. (selectBorderWidth/BorderWidth)

selectforeground=

Default value is system specific. (selectForeground/Background)

setgrid=

Default value is 0. (setGrid/SetGrid)

spacing1=

Default value is 0. (spacing1/Spacing)

spacing2=

Default value is 0. (spacing2/Spacing)

spacing3=

Default value is 0. (spacing3/Spacing)

state=

Default value is NORMAL. (state/State)

tabs=

No default value. (tabs/Tabs)

takefocus=

No default value. (takeFocus/TakeFocus)

undo=

Default is 0. (undo/Undo)

width=

Default value is 80. (width/Width)

wrap=

Default value is CHAR. (wrap/Wrap)

xscrollcommand=

No default value. (xScrollCommand/ScrollCommand)

yscrollcommand=

No default value. (yScrollCommand/ScrollCommand)

debug(boolean=None) [#]

Enables or disables debugging.

boolean

delete(start, end=None) [#]

Deletes the character (or embedded object) at the given position, or all text in the given range. Any marks within the range are moved to the beginning of the range.

start

Start index.

end

End index. If omitted, only one character is deleted.

dlineinfo(index) [#]

Calculates the bounding box for the line containing the given character.

This method only works if the text widget is updated. To make sure this is the case, you can call the update_idletasks method first.

index

Character index.

Returns:

A 5-tuple: (x, y, width, height, offset). The last tuple member is the offset from the top of the line to the baseline. If the line is not visible, this method returns None.

dump(index1, index2=None, command=None, **kw) [#]

Dumps the widget contents.

edit_modified(arg=None) [#]

The edit_modified method.

edit_redo() [#]

The edit_redo method.

edit_reset() [#]

The edit_reset method.

edit_separator() [#]

The edit_separator method.

edit_undo() [#]

The edit_undo method.

get(start, end=None) [#]

Returns the character at the given position, or all text in the given range.

start

Start position.

end

End position. If omitted, only one character is returned.

image_cget(index, option) [#]

Returns the current value of the given option. If there’s no image on the given position, this method raises a TclError exception. Not implemented in Python 1.5.2 and earlier.

index

Index specifier.

option

Image option.

Returns:

Option value.

image_configure(index, **options) [#]

Modifies one or more image options. If there’s no image on the given position, this method raises a TclError exception. Not implemented in Python 1.5.2 and earlier.

index

Index specifier.

**options

Image options.

align=

image=

An image object. This must be a PhotoImage or BitmapImage object, or any compatible object.

name=

padx=

pady=

image_create(index, cnf={}, **kw) [#]

Inserts an image at the given position. The image must be a a Tkinter PhotoImage or BitmapImage instance (or an instance of the corresponding PIL classes).

This method doesn’t work with Tk versions before 8.0. As a workaround, you can put the image in a Label widget, and use window_create to insert the label widget.

index

Index specifier.

**options

Image options. See image_config for a complete list.

image_names() [#]

Finds the names of all images embedded in the text widget. Tkinter doesn’t provide a way to get the corresponding PhotoImage or BitmapImage objects, but you can keep track of those yourself using a dictionary (using str(image) as the key).

Returns:

A tuple containing image names.

index(index) [#]

Returns the “line.column” index corresponding to the given index.

index

Index specifier.

Returns:

The corresponding row/column, given as a “line.column” string.

insert(index, text, *tags) [#]

Inserts text at the given position. The index is typically INSERT or END. If you provide one or more tags, they are attached to the new text.

If you insert text on a mark, the mark is moved according to its gravity setting.

index

Where to insert the text.

text

The text to insert.

*tags

Optional tags to attach to the text.

mark_gravity(self, name, direction=None) [#]

Sets the gravity for the given mark. The gravity setting controls how to move the mark if text is inserted exactly on the mark. If LEFT, the mark is not moved if text is inserted at the mark (that is, the text is inserted just after the mark). If RIGHT, the mark is moved to the right end of the text (that is, the text is inserted just before the mark). The default gravity setting is RIGHT.

name

The name of the mark.

direction

The gravity setting (LEFT or RIGHT). If this argument is omitted, the method returns the current gravity setting.

Returns:

The current gravity setting, if direction was omitted.

mark_names() [#]

Finds the names of all marks used in the widget. This includes the INSERT and CURRENT marks (but not END, which is a special index, not a mark).

Returns:

A tuple containing mark names.

mark_next(index) [#]

The mark_next method.

index

mark_previous(index) [#]

The mark_previous method.

index

mark_set(name, index) [#]

Moves the mark to the given position. If the mark doesn’t exist, it is created (with gravity set to RIGHT). You also use this method to move the predefined INSERT and CURRENT marks.

name

Mark name.

index

New position.

mark_unset(name) [#]

Removes the given mark from the widget. You cannot remove the builtin INSERT and CURRENT marks.

name

Mark name.

scan_dragto(x, y) [#]

Scrolls the widget contents. The text view is moved 10 times the distance between the scanning anchor and the new position.

x

y

scan_mark(x, y) [#]

Sets the scanning anchor. This anchor is used for fast scrolling.

x

y

search(pattern, index, stopindex=None, forwards=None, backwards=None, exact=None, regexp=None, nocase=None, count=None) [#]

Searches for text strings or regular expressions.

pattern

index

stopindex

forwards

backwards

exact

regexp

nocase

count

see(index) [#]

Makes sure a given position is visible. If the index isn’t visible, scroll the view as necessary.

index

Index specifier.

tag_add(tagName, index1, *args) [#]

The tag_add method.

tagName

index1

*args

tag_bind(tagName, sequence, func, add=None) [#]

The tag_bind method.

tagName

sequence

func

add

tag_cget(tagName, option) [#]

The tag_cget method.

tagName

option

tag_config(tagName, cnf={}, **kw) [#]

The tag_config method.

tagName

cnf

**kw

tag_configure(tagName, cnf={}, **kw) [#]

The tag_configure method.

tagName

cnf

**kw

tag_delete(*tagNames) [#]

The tag_delete method.

*tagNames

tag_lower(tagName, belowThis=None) [#]

The tag_lower method.

tagName

belowThis

tag_names(index=None) [#]

The tag_names method.

index

tag_nextrange(tagName, index1, index2=None) [#]

The tag_nextrange method.

tagName

index1

index2

tag_prevrange(tagName, index1, index2=None) [#]

The tag_prevrange method.

tagName

index1

index2

tag_raise(tagName, aboveThis=None) [#]

The tag_raise method.

tagName

aboveThis

tag_ranges(tagName) [#]

The tag_ranges method.

tagName

tag_remove(tagName, index1, index2=None) [#]

The tag_remove method.

tagName

index1

index2

tag_unbind(tagName, sequence, funcid=None) [#]

The tag_unbind method.

tagName

sequence

funcid

window_cget(index, option) [#]

Returns the current value of the given window option. If there’s no window on the given position, this method raises a TclError exception.

index

option

window_config(index, **options) [#]

Modifies one or more window options. If there’s no window on the given position, this method raises a TclError exception.

index

**options

align=

create=

padx=

pady=

stretch=

window=

Window object.

window_configure(index, cnf=None, **kw) [#]

Same as window_config.

window_create(index, **options) [#]

Inserts a widget at the given position. You can either create the widget (which should be a child of the text widget itself) first, and insert it using the window option, or provide a create callback which is called when the window is first displayed.

index

Index specifier.

**options

Window options. See window_config for a complete list.

window_names() [#]

Returns a tuple containing all windows embedded in the text widget. In 1.5.2 and earlier, this method returns the names of the widgets, rather than the widget instances.

Here’s how to convert the names to a list of widget instances in a portable fashion:

windows = text.window_names()
try:
    windows = map(text.nametowidget, windows)
except TclError:
    pass

Returns:

A list of window names.

xview(*what) [#]

The xview method.

*what

xview_moveto(fraction) [#]

The xview_moveto method.

fraction

xview_scroll(number, what) [#]

The xview_scroll method.

number

what

yview(*what) [#]

The yview method.

*what

yview_moveto(fraction) [#]

The yview_moveto method.

fraction

yview_pickplace(*what) [#]

The yview_pickplace method.

*what

yview_scroll(number, what) [#]

The yview_scroll method.

number

what

—

 

 

—