PySide Tree Model V: Building trees with QTreeWidget and QStandardItemModel

Last in a series on treebuilding in PySide: see Table of Contents.

As mentioned in post IIC, if our ultimate goal were to display a tree as simple as the one in the simpletreemodel, we would probably just use QTreeWidget or QStandardItemModel. In both cases, it is almost embarrassing how much easier it is to create the tree. This is because we don't need to roll our own model or data item classes.

In what follows, we will see how to use QTreeWidget and QStandardItemModel to create and view a read-only tree with multiple columns of data in each row. To keep it simple, we won't load data from a file, and the code only creates a very simple little tree. It would be a useful exercise to expand these examples to exactly mimic the GUI created in simpletreemodel.

QTreeWidget
While it is often poo-poohed as slow and inflexible, for simple projects QTreeWidget is extremely convenient and easy to use. Simply instantiate an instance of QTreeWidget, populate the tree with QTreeWidgetItem instances, and then call show() on the widget:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

from PySide import QtGui import sys app = QtGui.QApplication(sys.argv) treeWidget = QtGui.QTreeWidget() treeWidget.setColumnCount(2) treeWidget.setHeaderLabels(['Title', 'Summary']); #First top level item and its kids item0 = QtGui.QTreeWidgetItem(treeWidget, ['Title 0', 'Summary 0']) item00 = QtGui.QTreeWidgetItem(item0, ['Title 00', 'Summary 00'] ) item01 = QtGui.QTreeWidgetItem(item0, ['Title 01', 'Summary 01']) #Second top level item and its kids item1 = QtGui.QTreeWidgetItem(treeWidget, ['Title 1', 'Summary 1']) item10 = QtGui.QTreeWidgetItem(item1, ['Title 10', 'Summary 10']) item11 = QtGui.QTreeWidgetItem(item1, ['Title 11', 'Summary 11']) item12 = QtGui.QTreeWidgetItem(item1, ['Title 12', 'Summary 12']) #Children of item11 item110 = QtGui.QTreeWidgetItem(item11, ['Title 110', 'Summary 110']) item111 = QtGui.QTreeWidgetItem(item11, ['Title 111', 'Summary 111']) treeWidget.show() sys.exit(app.exec_())

QStandardItemModel
This is only slightly more complicated than QTreeWidget. We populate the tree with lists of  QStandardItems. To add a child to a row, we apply appendRow() to the first element (i.e., the first column) of the parent row:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36

from PySide import QtGui import sys app = QtGui.QApplication(sys.argv) model = QtGui.QStandardItemModel() model.setHorizontalHeaderLabels(['Title', 'Summary']) rootItem = model.invisibleRootItem() #First top-level row and children item0 = [QtGui.QStandardItem('Title0'), QtGui.QStandardItem('Summary0')] item00 = [QtGui.QStandardItem('Title00'), QtGui.QStandardItem('Summary00')] item01 = [QtGui.QStandardItem('Title01'), QtGui.QStandardItem('Summary01')] rootItem.appendRow(item0) item0[0].appendRow(item00) item0[0].appendRow(item01) #Second top-level item and its children item1 = [QtGui.QStandardItem('Title1'), QtGui.QStandardItem('Summary1')] item10 = [QtGui.QStandardItem('Title10'), QtGui.QStandardItem('Summary10')] item11 = [QtGui.QStandardItem('Title11'), QtGui.QStandardItem('Summary11')] item12 = [QtGui.QStandardItem('Title12'), QtGui.QStandardItem('Summary12')] rootItem.appendRow(item1) item1[0].appendRow(item10) item1[0].appendRow(item11) item1[0].appendRow(item12) #Children of item11 (third level items) item110 = [QtGui.QStandardItem('Title110'), QtGui.QStandardItem('Summary110')] item111 = [QtGui.QStandardItem('Title111'), QtGui.QStandardItem('Summary111')] item11[0].appendRow(item110) item11[0].appendRow(item111) treeView= QtGui.QTreeView() treeView.setModel(model) treeView.show() sys.exit(app.exec_())

While a tad more complicated than using QTreeWidget, this is still drastically simpler than subclassing QAbstractItemModel.

Conclusion
As is usually the case, there are many ways to get to the same destination. The route you take will depend on your goals, the complexity of your data, how much time you have to write your code, and how fast you want the program to be.  As mentioned before, it would be overkill to subclass QAbstractItemModel for a data store as simple as the one in simpletreemodel. This post shows just how easy it would be to create the exact same tree with an order of magnitude less code.

Those that have read any of these posts, thanks for reading! I'll be putting a PDF of all the posts together so you don't have to fight through a maze of posts for all the information.

PySide Tree Tutorial IV: What next?

Part of a series on treebuilding in PySide: see Table of Contents.

We have finished going over simpletreemodel. This and the final post are effectively appendices to our discussion of that example.

You have probably noticed that model/view programming is a complex subject, probably deserving book-length treatment. Tree views are the most complex built-in views there are, and hopefully we have made some headway on how to build them.

We have left out how we would handle an editable tree model (this is covered in the editabletreemodel example that comes with PySide). Nor have we addressed how to exert more precise control over how items are displayed, such as how to show html-formatted strings: this is the purview of custom delegates (a topic covered in the spinboxdelegate and stardelegate examples). We have also left open what to do if we want graphical rather than textual rendering of our data: this would involve the construction of a custom view (one example is to be found in chart).

For those that want a more principled overview of model/view programming in Python, Summerfield (2008) has three chapters on the topic. The brave can also try Summerfield (2010), for an extremely thorough treatment, and an entire chapter on trees. While the latter is not written for Python, it has tons of useful information about model-view programming if you can brave the translation from c++.

Summerfield, M (2010) Advanced Qt Programming. Prentice Hall.
Summerfield, M (2008) Rapid Gui Programming with Python and Qt. Prentice Hall.

PySide Tree Tutorial IIID: Creating the tree with setupModelData()

Part of a series on treebuilding in PySide: see Table of Contents
 
Recall that TreeModel uses setupModelData() to set up the initial tree structure. We provide a very brief description of its behavior here, and refer the reader to the code itself for more details (the code is in post IIIA). We begin with a text file (default.txt) that contains all the data for our tree:

Getting Started            How to familiarize yourself with Qt Designer
Launching Designer         Running the Qt Designer application
The User Interface         How to interact with Qt Designer
                             .
                             .
                             .
Connection Editing Mode    Connecting widgets together
Connecting Objects         Making connections in Qt Designer
Editing Connections        Changing existing connections

The entire text file is extracted in main, and sent to setupModelData() within TreeModel. Two tab-delimited strings are extracted from each line (the title and summary), and form the basis for a new TreeItem. The location of each node in the hierarchy is determined by the pattern of indentation in the file. We construct the tree exactly as discussed in Part II, using the following rules:

• For each line, create a TreeItem in which the two tab-delimited strings on that line are assigned to TreeItem.itemData (Figure 4, post IIB).
• If line N+1 is indented relative to line N, then make the (N+1)^th item a child of item N.
• If line N+1 is unindented relative to line N, then make the (N+1)^th item a sibling of item N's parent.

The implementation details in setupModelData() look a bit complicated, but most of the code is there for recordkeeping (e.g., keeping track of the current level of indentation). I found it helpful to work through how it handles the very first line of the input file, and then keep iterating through the code by hand until everything is clear.

PySide Tree Tutorial IIIC: Index and parent

Part of a series on treebuilding in PySide: see Table of Contents

Now we get to the guts of the API, and what really separates our model from a table model. If we were just building a table model, subclassing QAbstractTableModel, our model would be done. Because we are subclassing QAbstractItemModel, we must provide two additional methods: index() and parent(). The view needs these methods to navigate among items in the tree.

We can view index() and parent() as inverse methods; parent() takes in a child index and returns the index of its parent, while index() takes in a parent index and returns the index of one of its children (Figure 7A). We implement both methods as outlined in Figure 7B, which you might want to study before looking at the details of the code: it is sometimes easy to lose the forest for the trees with these functions.

Figure 7: Implementing parent() and index()   A. The basic logic of parent() and index(). TreeModel.parent() takes in the index of a child and returns the index of its parent, while TreeModel.index() takes in a parent index and returns the index of one of its children. B. Details about how parent() and index() are implemented. The flow of index() is counterclockwise (red arrows), and parent() is clockwise (green arrows). In each case, the given index's associated TreeItem is retrieved using internalPointer(). Then, its parent (child) item is accessed using the child() (parent()) method that was built into TreeItem. Finally, that item's index is created using createIndex(), which takes this item as one of its parameters. Figure 7B adapted from:  http://qt-project.org/doc/qt-4.8/itemviews-editabletreemodel.html

We'll start by looking at the implementation of index().

index(row, column, parent)

This method takes in the index of a parent item, and returns the index of one of its children. We implement it with:

def index(self, row, column, parent):
    if not self.hasIndex(row, column, parent):
        return QtCore.QModelIndex() 
    if not parent.isValid():
        parentItem = self.rootItem
    else:
        parentItem = parent.internalPointer() #returns item, given index
    childItem = parentItem.child(row) #the actual item we care about
    if childItem:
        return self.createIndex(row, column, childItem)
    else:
        return QtCore.QModelIndex() 

While the basic strategy here is outlined in Figure 7B, it also has to handle some special cases. First, we check the validity of the input coordinates with hasIndex(): it determines if row and column are nonnegative and fit within the range of values allowed by parent. For instance, if the parent item has three children, hasIndex() will return False if the row argument exceeds two.

If hasIndex() returns False, then the coordinates submitted by the view are not valid, and we return the invalid index. Otherwise, we retrieve the parentItem that corresponds to parent, and then extract that item's desired child using TreeItem.child(row).

Once we have extracted the appropriate child item from its parent, we wrap it up into an index using createIndex(row, column, childItem). This is the built-in method that all models use to create new indexes. It requires that we specify the item's row number and column number, as well the TreeItem to which the resulting index will refer--this is the item that its internalPointer() will return.

Recall that each element in TreeItem.itemData corresponds to a different column in a row of our model (Figure 4, post IIB). Hence, in general there is a many-to-one relationship (in this case a 2:1 relationship) between model indexes and TreeItems. Given N rows in our tree,then 2N calls to index() would be required to specify all the indexes.

parent(index) 
As discussed above, this method takes in an item's index, and returns the index of its parent:

def parent(self, index):   
        if not index.isValid():
            return QtCore.QModelIndex()
        childItem = index.internalPointer()
        parentItem = childItem.parent()
        if parentItem == self.rootItem:
            return QtCore.QModelIndex()
   return self.createIndex(parentItem.row(), 0, parentItem)

The basic strategy is illustrated in Figure 7B, but there are a few wrinkles we should consider. First, if the index is invalid (i.e., it is the root index), then it has no parent and we return an invalid index. Also, as discussed in part IIIA, we return the invalid index as the parent of any top-level items in the model, i.e., the items whose parents are rootItem.

For all lower-level items, we create the parent index with createIndex(). This is a little more subtle than in the index() method: we must specify the row and column numbers of the parentItem relative to its parent (i.e, the grandparent of childItem). To find the row that parentItem occupies among its siblings, we use TreeItem.row(). For the column value, we follow the convention that only items in the first column of our model have children (that is, we set the column parameter for createIndex() to zero).

Conclusion
We are pretty much done going over the code. While we will briefly discuss setupModelData() in the next post, we are done going over the API provided by the model for the view. Once the tree structure and model are built, then the model is ready to be connected to a view. This is easily done with QTreeView.setModel(TreeModel). When we call show() on the view, the GUI should appear on our screen as in Figure 3 (post IIA).

PySide Tree Tutorial IIIB: QAbstractItemModel's API

Part of a series on treebuilding in PySide: see Table of Contents.

In the next two posts, we will go through the methods instantiated in our model, starting now with  rowCount(), columnCount(), data(), and headerData(). In the following post we will round it out with a discussion of index() and parent(), which are especially important in hierarchical models.

Let's start with rowCount().

rowCount(parent) 
The rowCount() method takes a parent index and returns the number of children the corresponding parent item has. Views call rowCount() to determine how many rows need to be displayed underneath a given parent item.

Recall that in simple, single-level data structures like tables, each item has the same (invalid) parent, so we can get away with returning a single number in response to rowCount() (Figure 2 in post IB). This strategy won't work with tree models, in which different parents typically have different numbers of children.

In our example, rowCount() is implemented as follows:

def rowCount(self, parent):
    if parent.column() > 0:
        return 0
    if not parent.isValid():
        parentItem = self.rootItem
    else:
        parentItem = parent.internalPointer()
    return parentItem.childCount()

The basic strategy in rowCount() is to extract the parent index's corresponding parentItem and then return the number of children this item has using the built-in item method TreeItem.childCount(). The parentItem is extracted from its index using internalPointer(). While this might seem a strange name (Python has no pointers), you can think of internalPointer() as a getItemFromIndex() method that refers to the TreeItem corresponding to an index (Figure 6).

Figure 6: internalPointer() pulls an item from an index. Each index includes an internalPointer() method that returns the TreeItem associated with that index.

While the core calculation is relatively simple, there are a couple of wrinkles. First, our convention is that only the first column in a row has children, so if parent.column() is greater than 0, then rowCount() returns 0. Second, as discussed above, if the parent index is the invalid QModelIndex(), then the parent item is the root item. Finally, if the parent is not the root, then we follow the algorithm described in the previous paragraph.

columnCount(parent)
The columnCount() method takes in a parent index and returns the number of columns the corresponding parent item has. The view calls this method to ask the model how many columns to display under a parent item:

def columnCount(self, parent):
    if not parent.isValid():
        return self.rootItem.columnCount()
    else:
        return parent.internalPointer().columnCount()

The basic algorithm is simple: extract the parent item corresponding to the given parent index, and then call TreeItem's built-in columnCount() on this parent item. As before, if the parent index is invalid, we assume the index corresponds to the root item.

data(index, role)
Given an item's index and a desired role, data() tells the view what to display at that index's location:

def data(self, index, role):
    if not index.isValid():
        return None
    if role != QtCore.Qt.DisplayRole:
        return None
    item = index.internalPointer()
    return item.data(index.column())

The model does not know when it will be used, or which data the view will ask for. It lies in wait, providing data each time the view requests it, using the universal interface.

When the role is set as DisplayRole, the view is asking what text to display at the location specified by the given index. Recall that each TreeItem contains all the data for an entire row of the tree (Figure 4, post IIB), but the view needs to know what text to display in just one column. Luckily, each index already has a built-in column() method, and each TreeItem has a built-in data() method that returns the data from column j of that item. In TreeModel.data(), we compose these two functions to pull the appropriate column of data from the item corresponding to the given index.

When querying the model with data(), the view sends the index of the item to be displayed, as well as a single role parameter (of type QtCore.Qt.itemDataRole). What exactly is this itemDataRole? Roles are sent by the view to indicate the type of data it is looking for, such as text, font styles, background color, and other information.

Each role is sent as a separate call to TreeModel.data() by the view. The model should always return values of the appropriate type for a given role. A partial list of the different roles and their expected return type is shown in Table 2. You can find an exhaustive enumeration in the PySide documentation.

Role	Description	Expected return type
DisplayRole	Data to be displayed as text.	Python str
ToolTipRole	Text to temporarily display when you hover mouse over an item.	Python str
FontRole	Font with which to render items.	QtGui.QFont
TextAlignmentRole	Text alignment for item.	QtCore.Qt.AlignmentFlag
BackgroundRole	Set background color.	QtGui.QBrush

Table 2: Some itemDataRoles, their descriptions, and return types.

Our simpletreemodel example only supports the DisplayRole. However, it is instructive to play around with other roles. For instance you could try adding:

if role == QtCore.Qt.ToolTipRole:
    return "Scalawag!"

This will display the helpful tooltip "Scalawag!" over each item in the view when you hover over it with your mouse. To change the background color in the first column of the tree, try this:

if role == QtCore.Qt.BackgroundRole:
    if index.column() == 0:
        return QtGui.QBrush(QtGui.QColor(QtCore.Qt.yellow))

The result is ugly, to be sure, but it's the principal that matters.

Some developers argue that this functionality, whereby the model controls how items appear, violates the desired division of labor between views and models. This is a valid concern, and some programmers leave all such appearance customization to delegates. But since we are ignoring delegates for now, it is useful to know how to sneak formatting in via the model.

headerData(section, orientation, role)
The headerData() function extracts the header data from the root item, and paints it in the column headers:

def headerData(self, section, orientation, role):
    if orientation==QtCore.Qt.Horizontal and role==QtCore.Qt.DisplayRole:
        return self.rootItem.data(section)
    return None

headerData() works similarly to TreeModel.data(). Note also that section is a generic term for the row or column number, depending on whether the orientation is vertical or horizontal, respectively.