24. Model-View Programming with QAbstractItemModel

Of the three abstract models we have seen so far, QAbstractItemModel is the most inconvenient to subclass - not because it is more difficult but because QAbstractListModel and QAbstractTableModel, being specialized for lists and tables, provide default implementations for some methods that you have to implement yourself for QAbstractItemModels. At the same time, this makes QAbstractItemModel the most flexible of the three, and suitable for representing more complex data structures such as trees.

In this chapter, we implement a series of models suitable for representing hierarchical data structures to be viewed in a tree view.

In addition to data() and rowCount() which are required for a QAbstractListModel subclass and columnCount() which is additionally required for a QAbstractTableModel subclass, creating a read-only QAbstractItemModel subclass requires reimplementing two more methods:

• index(row, column, parent), which returns a QModelIndex for the item at the given row and column under the given parent index.

• parent(index), which returns the QModelIndex of the parent of the item with the given index.

These two methods are roughly inverse to each other: index() navigates down the tree (from parent to child), while parent() navigates up (from child to parent). In both cases there are a few edge cases you need to take into account.

To create a basic read-only tree model:

1. Create a Python class to represent a node in the tree. Python does not provide a built-in tree data structure so we make our own. Each TreeItem holds a value, a reference to its parent, and a list of children. When a parent is provided, the item automatically appends itself to the parent’s children. The class method build_tree() reads the JSON file and builds the full tree.

2. Subclass QAbstractItemModel and implement rowCount(), columnCount(), and data(). These methods are already covered in the two previous chapters with the difference that rowCount() has to account for the tree structure: if the parent index is valid, the row count is the number of children of the item it points to and the number of the root item’s children otherwise.

3. Implement index(). We first call hasIndex() to check whether the requested position is out of bounds, returning an invalid QModelIndex if so. We then determine the parent item: if parent is valid, we get it via internalPointer(); otherwise the parent item is the root item. Finally, we call createIndex() with the row, column and a reference to the child item, and return the result.

   hasIndex() determines whether the row, column and parent combination would return a valid index, but it does not tell us if the parent itself is valid. A valid position can exist under either a valid parent item or the invisible root, so we still need to distinguish between the two.

4. Implement parent(). This method returns the parent of the item with the given index. If index is invalid we return an invalid QModelIndex immediately. Otherwise we retrieve the item via internalPointer() and get its parent. If the parent is the root, we again return an invalid QModelIndex. Otherwise, we determine the parent’s row within its own parent’s children list and return a QModelIndex created with createIndex().

In the main window, create a model and view instances and bind them. When you run the code a read-only tree view with a single column is shown:

To create a read-only tree model with multiple columns:

1. Implement the tree node class. The implementation is similar to the previous example but we add several helper methods and store item data as a list to support multiple columns:

   • child(row) - returns the child item at given row.
   • child_count() - returns the number of children.
   • column_count() - returns the number of columns.
   • data(column) - returns the data for the given column
   • row() - returns the item’s own row index within its parent’s children list.

   We also extract item creation into a separate create_item() static method.

2. Subclass QAbstractItemModel and implement rowCount(), columnCount(), data() and headerData(). We make several changes compared to the previous example:

   • rowCount() uses TreeItem.child_count() instead of len(children) directly. Note that it also returns zero for any column other than the first one - it is a Qt convention for tree models that only items in the first column have children.
   • columnCount() uses TreeItem.column_count()
   • data() uses TreeItem.data(), passing the index column to get the correct field.
   • headerData() returns the appropriate label from the header list.

3. Implement index() and parent(). The logic is the same as in the previous example, with two changes:

   • index() uses TreeItem.child() to retrieve the child item instead of accessing children directly.
   • parent() uses TreeItem.row() to determine the parent’s row instead of calling parent.children.index() directly.

The main window code remains unchanged. When you run it a multi-column tree view is shown:

To make a QAbstractItemModel subclass editable:

1. Add the setData() method to the tree node class. This method sets the value at the given column in the item’s data.

2. In the model, update data() to also handle EditRole in addition to DisplayRole.

3. Implement flags(). As in previous chapters, return the base flags plus Qt.ItemFlag.ItemIsEditable to signal to the view that items can be edited. Return an empty Qt.ItemFlags() for invalid indices.

4. Implement setData(). Check that the role is EditRole and that the new value is different from the current one. If so, call tree_item.setData() to update the data, emit dataChanged() and return True. Return False otherwise.

Now, if you double-click a cell in the tree view, an editor opens and you can edit its value. Note that changes are only saved in memory.

To create a resizable tree model:

1. Add a class-level counter to TreeItem to assign unique IDs to newly inserted nodes.

2. Add two new methods to TreeItem:

   • insert_child(row) creates a new TreeItem with a unique ID and empty fields and inserts it at the given row in the parent’s children list.
   • remove_child(row) removes the child at the given row using slice assignment. Note that unlike previous examples, __init__() no longer auto-appends the item to its parent. This is done in insert_child().

3. Implement insertRows() in the model. Check that the requested row is within bounds using rowCount(parent), then guard the insertion with beginInsertRows() and endInsertRows().

4. Implement removeRows(). Guard the removal with beginRemoveRows() and endRemoveRows().

In the main window, add three buttons: Insert sibling, Insert child, and Remove current:

• Insert sibling inserts a new row at row + 1 under the curent index’s parent, placing the new node below the selected one at the same level.
• Insert child inserts a new row under the current index itself, making it a child of the selected node.
• Remove current removes the selected row from its parent.

When you run the code you’ll see a tree view with buttons to insert and remove nodes: