A treeview widget can display and allow browsing through a hierarchy of items, and can show one or more attributes of each item as columns to the right of the tree.
Treeview widgets are created using the ttk.Treeview function:
tree = ttk.Treeview(parent)
Adding Items to the Tree
Items are created by inserting them into the tree, using the treeview's '"insert" method. To insert an item, you need to know where in the tree to insert it, which means specifying the parent item as well as what position in the list of the parent's children the new item should be inserted at.
The treeview widget automatically creates a root node (which is not displayed), having the id of "{}"(i.e. the empty string), which can serve as the parent of the first level of items you add. Positions within the list of the parent's children are specified by index (0 being the first, with the special"end" index meaning inserting after all existing children).
# Inserted at the root, program chooses id:
tree.insert('', 'end', 'widgets', text='Widget Tour')
# Same thing, but inserted as first child:
tree.insert('', 0, 'gallery', text='Applications')
# Treeview chooses the id:
id = tree.insert('', 'end', text='Tutorial')
# Inserted underneath an existing node:
tree.insert('widgets', 'end', text='Canvas')
tree.insert(id, 'end', text='Tree')
Inserting the item returns the id of the newly created item.
Rearranging Items
A node (and its descendants, if any) can be moved to a different location in the tree; the only restriction is that a node cannot be moved underneath one of its descendants. The target location is specified via parent and index into the list of children, as was done with "insert".
tree.move('widgets', 'gallery', 'end'); # move widgets under gallery
Items can be
detached from the tree, which removes the item and its descendants from the hierarchy,but does not destroy the items, allowing you to later reinsert them with
"move".
tree.detach('widgets')
Items can also be
deleted, which does completely get rid of the item and its descendants.
tree.delete('widgets')
If you'd like to navigate the hierarchy, there are methods that let you find the parent of an item (
"parent"),find the next or previous siblings of an item (
"next" and
"prev"), and return the list of children of an item (
"children").
You can control whether or not the item is open and shows its children by modifying the "open" item configuration option.
tree.item('widgets', open=TRUE)
isopen = tree.item('widgets', 'open')
Displaying Information for each Item
The treeview can also display one or more additional pieces of information about each item, which are shown as columns to the right of the main tree display.
Again, each column is referenced by a symbolic name that you assign. You can specify the list of columns using the "columns" configuration option of the treeview widget, either when first creating the widget, or later on.
tree = ttk.Treeview(root, columns=('size', 'modified'))
tree['columns'] = ('size', 'modified', 'owner')
You can specify the width of the column, how the display of item information in the column is aligned,and more. You can also provide information about the heading of the column, such as the text to display,an optional image, alignment, and a script to invoke when the item is clicked (e.g. to sort the tree).
tree.column('size', width=100, anchor='center')
tree.heading('size', text='Size')
The values to place in each column for each item can be specified either individually, or by providing a list of values for the item. In the latter case, this is done using the
"values"item configuration option (and so can be used either when first inserting the item or later) which takes a list of the values; the order of the list must be the same as the order in the
"columns"widget configuration option.
tree.set('widgets', 'size', '12KB')
size = tree.set('widgets', 'size')
tree.insert('', 'end', text='Listbox', values=('15KB Yesterday mark'))
Item Appearance and Events
Like the text and canvas widgets, the treeview widget uses tags to help you modify the appearance of items in the tree. You can assign a list of tags to each item using the "tags"item configuration option (again, when creating the item or later on).
Tag configuration options can then be specified, which will then apply to all items having that tag. Valid tag options include "foreground" (text color), "background","font", and "image" (not used if the item specifies its own image).
tree.insert('', 'end', text='button', tags=('ttk', 'simple'))
tree.tag_configure('ttk', background='yellow')
tree.tag_bind('ttk', '<1>', itemClicked); # the item clicked can be found via tree.focus()
The treeview will generate virtual events
"<TreeviewSelect>",
"<TreeviewOpen>" and
"<TreeviewClose>" which allow you to monitor changes to the widget made by the user.You can use the
"selection" method to determine the current selection (the selection can also be changed from your program).
Customizing the Display
- Specify the desired number of rows to show using the "height" widget configuration option.
- Control the width of each column using the column's "width" or "minwidth" options. The column holding the tree can be accessed with the symbolic name "#0". The overall requested width for the widget is based on the sum of the column widths.
- Choose which columns to display and the order to display them in using the "displaycolumns" widget configuration option.
- You can optionally hide one or both of the column headings or the tree itself (leaving just the columns) using the "show" widget configuration option (default is "tree headings" to show both).
- You can specify whether a single item or multiple items can be selected by the user via the "selectmode" widget configuration option, passing "browse" (single item), "extended" (multiple items, the default), or "none".