Tkinter 8.5 reference: a GUI for Python

45. ttk.Treeview

The purpose of the ttk.Treeview widget is to
present a hierarchical structure so that the user can use mouse
actions to reveal or hide any part of the structure.

The association with the term “tree” is due to
programming practice: tree structures are a commonplace in
program design. Strictly speaking, the hierarchy shown in a
Treeview widget is a forest: there is no one
root, just a collection of top-level nodes, each of which may contain second-level
nodes, each of which may contain third-level nodes, and so on.

You may have encountered this particular presentation as a
way of browsing a directory or folder hierarchy. The
entire hierarchy is displayed like an indented outline,
where each directory is on a separate line, and
the subdirectories of each directory are displayed
underneath that line, indented:

The user can click on the icon for a directory to collapse (close) it, hiding all of the items in
it. They can also click again on the icon to expand (open) it, so that the items in the
directory or folder are shown.

The Treeview widget generalizes this concept
so that you can use it to display any hierarchical structure,
and the reader can collapse or expand subtrees of this
structure with the mouse.

First, some definitions:

item

One of the entities being displayed in the widget.
For a file browser, an item might be either a
directory or a file.

Each item is associated with a textual label, and
may also be associated with an image.

iid

Every item in the tree has a unique identifier string
called the iid. You can supply
the iid values yourself, or you can let ttk generate
them.

child

The items directly below a given item in a hierarchy. A
directory, for example, may have two kinds of children:
files and subdirectories.

parent

For a given item, if it is at the top of the
hierarchy it is said to have no parent; if it is
not at the top level, the parent is the item that
contains it.

ancestor

The ancestors of an item include its parent, its parent's
parent, and so on up to the top level of the tree.

visible

Top-level items are always visible. Otherwise, an item is
visible only if all its ancestors are expanded.

descendant

The descendants of an item include its children, its
childrens' children, and so on. Another way of saying
this is that the subtree of an item includes all its
descendants.

tag

Your program can associate one or more tag strings with each item. You can use
these tags to control the appearance of an item. For
example, you could tag directories with the tag 'd' and files with the tag 'f',
and then specify that items with tag 'd'
use a boldface font.

You may also associate events with tags, so that certain
events will cause certain handlers to be called for all
items that have that tag. For example, you could set up a
file browser so that when a user clicks on a directory,
the browser updated its contents to reflect the current
file structure.

Your Treeview widget will be structured with
multiple columns. The first column, which we'll call the
icon column, displays the icons that
collapse or expand items. In the remaining columns, you may
display whatever information you like.

For example, a simple file browser widget might use two columns,
with the directory icons in the first column and the directory
or file name in the second columns. Or you might wish to
display file sizes, permissions, and other related data in
additional columns.

The operations of the Treeview widget even allow
you to use it as a tree editor. Your program can remove an
entire subtree from its location in the main tree and then
attach it later at an entirely different point.

Here is the general procedure for setting up a Treeview widget.

Create the widget with the ttk.Treeview
constructor. Use the columns keyword
argument to specify the number of columns to be displayed
and to assign symbolic names to each column.

Use the .column() and .heading() methods to set up column headings (if you want them) and
configure column properties such as size and stretchability.

Starting with the top-level entries, use the .insert() method to populate the tree. Each call
to this method adds one item to the tree. Use the open keyword argument of this method to specify
whether the item is initially expanded or collapsed.

If you want to supply the iid value for this item, use the
iid keyword argument. If you omit this
argument, ttk will make one up and return it as the
result of the .insert() method call.

Use the values keyword argument of this
method to specify what should appear in each column of this
item when it is visible.

To create a Treeview widget within a given parent widget:

w = ttk.Treeview(parent, option=value, ...)

The constructor returns the new Treeview widget.
Its options include:

class_

You may provide a widget class name when you create this
widget. This name may be used to customize the widget's
appearance; see Section 27, “Standardizing appearance”.
Once the widget is created, the widget class name cannot
be changed.

columns

A sequence of column identifier strings. These
strings are used internally to identify the columns
within the widget. The icon column, whose identifier
is always '#0', contains the
collapse/expand icons and is always the first column.

The columns you specify with the columns argument are in addition to the icon column.

For example, if you specified columns=('Name',
'Size'), three columns would appear in the
widget: first the icon column, then two more columns
whose internal identifiers are 'Name'
and 'Size'.

cursor

Use this option to specify the appearance of the mouse
cursor when it is over the widget; see Section 5.8, “Cursors”. The default value (an empty
string) specifies that the cursor is inherited from the
parent widget.

displaycolumns

Selects which columns are actually displayed and
determines the order of their presentation. Values
may be:

'#all' to select all columns
and display them in the order defined by the
columns argument.

A list of column numbers (integer positions,
counting from 0) or column identifiers from the
columns argument.

For example, suppose you specify columns=('Name', 'Size', 'Date'). This
means each call to the .insert()
method will require an argument values=(name,
size, date) to supply the values
that will be displayed. Let's call this sequence
the logical column sequence.

Further suppose that in the constructor you
specify columns=(2,0). The
physical column sequence,
the columns that will actually appear in the
widget, will be three: the icon column will be
first, followed by the date column (index 2 in the
logical column sequence), followed by the name
column (logical column index 0). The size column
will not appear.

You could get the same effect by specifying column
identifiers instead of logical column positions:
columns=('Date', 'Name').

height

The desired height of the widget, in rows.

padding

Use this argument to place extra space around the
contents inside the widget. You may provide either
a single dimension
or a sequence of up to four dimensions, interpreted
according to this table:

Values given

Left

Top

Right

Bottom

a

a

a

a

a

a b

a

b

a

b

a b c

a

c

b

c

a b c d

a

b

c

d

selectmode

This option controls what the user is allowed to select
with the mouse. Values can be:

selectmode='browse'

The user may select only one item at a time.

selectmode='extended'

The user may select multiple items at once.

selectmode='none'

The user cannot select items with the mouse.

show

To suppress the labels at the top of each column,
specify show='tree'. The default is to
show the column labels.

Use this option to specify whether a widget is visited
during focus traversal; see Section 53, “Focus: routing keyboard input”.
Specify takefocus=True if you want the
visit to accept focus; specify takefocus=False if the widget is not to accept
focus. The default value is an empty string; by
default, ttk.Treeview widgets do get
focus.

Here are the methods available on a Treeview
widget.

.bbox(item,
column=None)

For the item with iid item, if the item is currently
visible, this method returns a tuple (x, y,
w, h), where (x, y)
are the coordinates of the upper left corner of that item
relative to the widget, and w and h are the width and height of the
item in pixels. If the item is not visible, the method
returns an empty string.

If the optional column argument is omitted,
you get the bounding box of the entire row. To get the
bounding box of one specific column of the item's row, use
column=C where
C is either
the integer index of the column or its column identifier.

.column(cid, option=None, **kw)

This method configures the appearance of the logical
column specified by cid, which may be either a column index or a column
identifier. To configure the icon column, use a cid value of '#0'.

Each column in a Treeview widget has its
own set of options from this table:

anchor

The anchor that
specifies where to position the content of the
column. The default value is 'w'.

id

The column name. This option is read-only and
set when the constructor is called.

minwidth

Minimum width of the column in pixels; the default
value is 20.

stretch

If this option is True, the
column's width will be adjusted when the widget is
resized. The default setting is 1.

width

Initial width of the column in pixels; the default
is 200.

If no option value or any other keyword argument is supplied, the
method returns a dictionary of the column options for
the specified column.

To interrogate the current value of an option named
X, use an
argument option=X.

To set one or more column options, you may pass
keyword arguments using the option names shown above,
e.g., anchor=tk.CENTER to center the
column contents.

.delete(*items)

The arguments are iid values. All the items in the widget
that have matching iid values are destroyed, along with
all their descendants.

.detach(*items)

The arguments are iid values. All the items in the widget
that have matching iid values are removed from the visible
widget, along with all their descendants.

The items are not destroyed. You may reattach them to the
visible tree using the .move() method
described below.

.exists(iid)

Returns True if there exists an item in the
widget with the given iid, or False
otherwise. If an item is not currently visible because it
was removed with the .detach() method, it
is still considered to exist for the purposes of the .exists() method.

.focus([iid])

If you don't provide an argument to this method, you get
back either the iid of the item that currently has focus,
or '' if no item has focus.

You can give focus to an
item by passing its iid as the argument to this method.

.get_children([item])

Returns a tuple of the iid values of the children of the
item specified by the item argument. If the argument is
omitted, you get a tuple containing the iid values of the
top-level items.

.heading(cid,
option=None, **kw)

Use this method to configure the column heading that
appears at the top of the widget for the column specified
by cid, which
may be either a column index or a column identifier. Use
a cid argument
value of '#0' to configure the heading over
the icon column.

Each heading has its own set of options with these names
and values:

anchor

An anchor that specifies how the heading is
aligned within the column; see Section 5.5, “Anchors”. The default value is tk.W.

command

A procedure to be called when the user clicks on
this column heading.

image

To present a graphic in the column heading (either
with or instead of a text heading), set this
option to an image, as specified in Section 5.9, “Images”.

text

The text that you want to appear in the column
heading.

If you supply no keyword arguments, the method will
return a dictionary showing the current settings of
the column heading options.

To interrogate the current value of some heading
option X,
use an argument of the form option=X; the method will return the
current value of that option.

You can set one or more heading options by supplying
them as keyword arguments such as “anchor=tk.CENTER”.

.identify_column(x)

Given an x coordinate, this
method returns a string of the form '#n' that identifies the column that
contains that x coordinate.

Assuming that the icon column is displayed, the value of
n is 0 for the
icon column; 1 for the second physical column; 2 for the
third physical column; and so on. Recall that the
physical column number may be different from the logical
column number in cases where you have rearranged them
using the displaycolumns argument to the
Treeview constructor.

If the icon column is not displayed, the value of n is 1 for the first
physical column, 2 for the second, and so on.

.identify_element(x,
y)

Returns the name of the element at location (x, y) relative to the widget, or
'' if no element appears at that position.
Element names are discussed in Section 50, “The ttk element layer”.

.identify_region(x,
y))

Given the coordinates of a point relative to the widget,
this method returns a string indicating what part of the
widget contains that point. Return values may include:

'nothing'

The point is not within a functional part of the
widget.

'heading'

The point is within one of the column headings.

'separator'

The point is located within the column headings
row, but on the separator between columns. Use
the .identify_column() method to
determine which column is located just to the
left of this separator.

'tree'

The point is located within the icon column.

'cell'

The point is located within an item row but not
within the icon column.

.identify_row(y)

If y-coordinate y is within one of
the items, this method returns the iid of that item. If
that vertical coordinate is not within an item, this
method returns an empty string.

.index(iid)

This method returns the index of the item with the
specified iid
relative to its parent, counting from zero.

.set_children(item,
*newChildren)

Use this method to change the set of children of the item
whose iid is item. The newChildren argument is a sequence
of iid strings. Any current children of item that are not in
newChildren
are removed.

.insert(parent,
index, iid=None, **kw)

This method adds a new item to the tree, and returns the
item's iid value. Arguments:

parent

To insert a new top-level item, make this argument
an empty string. To insert a new item as a child
of an existing item, make this argument the parent
item's iid.

index

This argument specifies the position among this
parent's children where you want the new item to
be added. For example, to insert the item as
the new first child, use a value of zero; to
insert it after the parent's first child, use a
value of 1; and so on. To add the new item as
the last child of the parent, make this argument's
value 'end'.

iid

You may supply an iid for the item as a string
value. If you don't supply an iid, one will be
generated automatically and returned by the
method.

You may also specify a number of item options as keyword
arguments to this method.

image

You may display an image just to the right of the
icon for this item's row by providing an image=I
argument, where I is an image as specified
in Section 5.9, “Images”.

open

This option specifies whether this item will be
open initially. If you supply open=False, this item will be closed. If
you supply open=True, the item's
children will be visible whenever the item itself
is visible. The default value is False.

tags

You may supply one or more tag strings to be
associated with this item. The value may be
either a single string or a sequence of strings.

text

You may supply text to be displayed within the
icon column of this item. If given, this text
will appear just to the right of the icon, and
also to the right of the image if provided.

values

This argument supplies the data items to be
displayed in each column of the item. The values
are supplied in logical column order. If too few
values are supplied, the remaining columns will be
blank in this item; if too many values are
supplied, the extras will be discarded.

.item(iid[, option[, **kw]])

Use this method to set or retrieve the options within the
item specified by iid. Refer to the .insert() method
above for the names of the item options.

With no arguments, it returns a dictionary whose keys are
the option names and the corresponding values are the
settings of those options. To retrieve the value of a
given option, pass the option's name as its second
argument. To set one or more options, pass them as
keyword arguments to the method.

.move(iid, parent, index)

Move the item specified by iid to the values under the item
specified by parent at position index. The parent and index arguments work the same as
those arguments to the .index() method.

.next(iid)

If the item specified by iid is not the last child of its
parent, this method returns the iid of the following
child; if it is the last child of its parent, this method
returns an empty string. If the specified item is a
top-level item, the method returns the iid of the next
top-level item, or an empty string if the specified item
is the last top-level item.

.parent(iid)

If the item specified by iid is a top-level item, this
method returns an empty string; otherwise it returns the
iid of that item's parent.

.prev(iid)

If the item specified by iid is not the first child of its
parent, this method returns the iid of the previous child;
otherwise it returns an empty string. If the specified
item is a top-level item, this method returns the iid of
the previous top-level item, or an empty string if it is
the first top-level item.

.see(iid)

This method ensures that the item specified by iid is visible. Any
of its ancestors that are closed are opened. The widget
is scrolled, if necessary, so that the item appears.

.selection_add(items)

In addition to any items already selected, add the
specified items. The argument may be either a single iid or a sequence
of iids.

.selection_remove(items)

Unselect any items specified by the argument, which may be
a single iid or a sequence of iids.

.selection_set(items)

Only the specified items will be selected; if any other items were
selected before, they will become unselected.

.selection_toggle(items)

The argument may be a single iid or a sequence of iids.
For each item specified by the argument, if it was
selected, unselect it; if it was unselected, select it.

.set(iid, column=None,
value=None)

Use this method to retrieve or set the column values of
the item specified by iid. With one argument, the
method returns a dictionary: the keys are the column
identifiers, and each related value is the text
in the corresponding column.

With two arguments, the method returns the data value from
the column of the selected item whose column identifier is
the column argument. With three arguments,
the item's value for the specified column is set to the
third argument.

.tag_bind(tagName,
sequence=None, callback=None)

This method binds the event handler specified by the callback argument to all items that have tag
tagName. The
sequence and callback
arguments work the same as the sequence and
func arguments of the .bind() method described in Section 26, “Universal widget methods”.

.tag_configure(tagName,
option=None, **kw)

This method can either interrogate or set options that
affect the appearance of all the items that have tag tagName. Tag options include:

When called with one argument, it returns a dictionary of
the current tag options. To return the value of a
specific option X, use X as the second argument.

To set one or more options, use keyword arguments such as
foreground='red'.

.tag_has(tagName[,
iid])

Called with one argument, this method returns a list of
the iid values for all items that carry tag tagName. If you
provide an iid as the second argument, the method returns
True if the item with that iid has tag
tagName, False otherwise.