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. Where Chapter 22 modeled a bank’s client roster and Chapter 23 modeled an account’s transactions, this chapter models the budget those transactions are measured against - a hierarchy of categories and line items.

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.

Like the previous two chapters, a QAbstractItemModel subclass sits between a data source and a view - but this time we need two extra methods to make navigating the hierarchy possible:

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:

Rent and Utilities are both children of Housing, so they are row = 0 and row = 1 under Housing, regardless of Housing’s own position under Expenses. This is why index() and parent() both take a parent argument: the same row number means something different depending on which parent you’re asking about.

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. Category nodes like Expenses, Housing, and Transportation only populate the name column. The budget and actual columns are left empty since those nodes represent groupings, not individual line items.

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 (‘Category’, ‘Budget’, ‘Actual’).

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. Category rows like Housing and Transportation remain technically editable in this simple example, even though their budget and actual columns are always empty. A production model would likely flag those specific cells as read-only.

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 current 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:

Unlike TxtFileModel and CsvFileModel in the previous two chapters, JsonModel finally has to reimplement parent(). Every time QTreeView expands a node, computes indentation, or walks up to find an ancestor, it asks the model for that item’s parent.

Across these three chapters you’ve built a QAbstractListModel, a QAbstractTableModel, and now a QAbstractItemModel You choose which one of them to inherit from by answering this question: what shape is your data? But that decision is independent of a second one you’ll need to make in real applications: which view, QListView, QTableView, or QTreeView should display it? These two questions don’t have to agree.

Every standard Qt view can technically accept every model shape. When there is a mismatch like showing a tree in a list view, nothing crashes - a view simply shows less of the model than a matched view would:

Model choice tracks the shape of your source data, while view choice tracks what the user needs to see and do with it:

• QListView - Single value per row (or icon-grid) display. You choose it when the user needs to pick from a set of things, not compare their attributes.
• QTableView - A full grid with visible, sortable columns. You choose it when the user needs to compare fields across rows side by side.
• QTreeView - The only one of the three that exposes hierarchy interactively. You choose it specifically when you need a navigable tree structure.
• QComboBox Constrained single-choice input from a popup.

This independence is also why the same model can legitimately be handed to more than one view at once. A QSortFilterProxyModel (covered in section 26.4) is an example of code that has to stay shape-agnostic: it’s built directly on QAbstractItemModel, so the same proxy model can be used with either a flat table or a tree. Also,in section 26.9 we’ll take CsvModel from Chapter 23 and attach it to two views simultaneously: a QListView and a full QTableView.