QGenericItemModel Class

Detailed Description

QGenericItemModel can make the data in any sequentially iterable C++ type available to the model/view framework of Qt. This makes it easy to display existing data structures in the Qt Widgets and Qt Quick item views, and to allow the user of the application to manipulate the data using a graphical user interface.

To use QGenericItemModel, instantiate it with a C++ range and set it as the model of one or more views:

std::array<int, 5> numbers = {1, 2, 3, 4, 5};
QGenericItemModel model(numbers);
listView.setModel(&model);

The range can be any C++ type for which the standard methods std::cbegin and std::cend are implemented, and for which the returned iterator type satisfies std::forward_iterator. Certain model operations will perform better if std::size is available, and if the iterator satisfies std::random_access_iterator.

The range can be provided by pointer or by value, and has to be provided when constructing the model. If the range is provided by pointer, then QAbstractItemModel APIs that modify the model, such as setData() or insertRows(), modify the range. The caller must make sure that the range's lifetime exceeds the lifetime of the model. Methods that modify the structure of the range, such as insertRows() or removeColumns(), use standard C++ container APIs resize(), insert(), erase(), in addition to dereferencing a mutating iterator to set or clear the data.

There is no API to retrieve the range again, so constructing the model from a range by value is mostly only useful for displaying data. Changes to the data can be monitored using the signals emitted by the model, such as dataChanged().

Read-only or mutable

For ranges that are const objects, for which access always yields constant values, or where the required container APIs are not available, QGenericItemModel implements write-access APIs to do nothing and return false. In the example above, the model cannot add or remove rows, as the number of entries in a C++ array is fixed. But the values can be changed using setData(), and the user can trigger editing of the values in the list view. By making the array const, the values also become read-only.

const std::array<int, 5> numbers = {1, 2, 3, 4, 5};

The values are also read-only if the element type is const, like in

std::array<const int, 5> numbers = {1, 2, 3, 4, 5};

List, Table, or Tree

The elements in the range are interpreted as rows of the model. Depending on the type of these rows, QGenericItemModel exposes the range as a list, a table, or a tree.

If the row type is not an iterable range, and does not implement the C++ tuple protocol, then the range gets represented as a list.

QList<int> numbers = {1, 2, 3, 4, 5};
QGenericItemModel model(numbers); // columnCount() == 1
QListView listView;
listView.setModel(&model);

If the row type is an iterable range, then the range gets represented as a table.

std::vector<std::vector<int>> gridOfNumbers = {
    {1, 2, 3, 4, 5},
    {6, 7, 8, 9, 10},
    {11, 12, 13, 14, 15},
};
QGenericItemModel model(&gridOfNumbers); // columnCount() == 5
QTableView tableView;
tableView.setModel(&model);

With such a row type, the number of columns can be changed via insertColumns() and removeColumns(). However, all rows are expected to have the same number of columns.

Fixed-size rows

If the row type implements the C++ tuple protocol, then the range gets represented as a table with a fixed number of columns.

using TableRow = std::tuple<int, QString>;
QList<TableRow> numberNames = {
    {1, "one"},
    {2, "two"},
    {3, "three"}
};
QGenericItemModel model(&numberNames); // columnCount() == 2
QTableView tableView;
tableView.setModel(&model);

An easier and more flexible alternative to implementing the tuple protocol for a C++ type is to use Qt's meta-object system to declare a type with properties. This can be a value type that is declared as a gadget, or a QObject subclass.

class Book
{
    Q_GADGET
    Q_PROPERTY(QString title READ title)
    Q_PROPERTY(QString author READ author)
    Q_PROPERTY(QString summary MEMBER m_summary)
    Q_PROPERTY(int rating READ rating WRITE setRating)
public:
    Book(const QString &title, const QString &author);

    // C++ rule of 0: destructor, as well as copy/move operations
    // provided by the compiler.

    // read-only properties
    QString title() const { return m_title; }
    QString author() const { return m_author; }

    // read/writable property with input validation
    int rating() const { return m_rating; }
    void setRating(int rating)
    {
        m_rating = qBound(0, rating, 5);
    }

private:
    QString m_title;
    QString m_author;
    QString m_summary;
    int m_rating = 0;
};

Using QObject subclasses allows properties to be bindable, or to have change notification signals. However, using QObject instances for items has significant memory overhead.

Using Qt gadgets or objects is more convenient and can be more flexible than implementing the tuple protocol. Those types are also directly accessible from within QML. However, the access through the property system comes with some runtime overhead. For performance critical models, consider implementing the tuple protocol for compile-time generation of the access code.

Trees of data

QGenericItemModel can represent a data structure as a tree model. Such a tree data structure needs to be homomorphic: on all levels of the tree, the list of child rows needs to use the exact same representation as the tree itself. In addition, the row type needs be of a static size: either a gadget or QObject type, or a type that implements the {C++ tuple protocol}.

To represent such data as a tree, the row type has to implement a traversal protocol that allows QGenericItemModel to navigate up and down the tree. For any given row, the model needs to be able to retrieve the parent row, and the span of children for any given row.

class TreeRow;

using Tree = std::vector<TreeRow>;

The tree itself is a vector of TreeRow values. See Rows as pointers or values for the considerations on whether to use values or pointers of items for the rows.

class TreeRow
{
    Q_GADGET
    // properties

    TreeRow *m_parent;
    std::optional<Tree> m_children;

public:
    TreeRow() = default;

    // rule of 0: copy, move, and destructor implicitly defaulted

The row class can be of any fixed-size type described above: a type that implements the tuple protocol, a gadget, or a QObject. In this example, we use a gadget.

Each row item needs to maintain a pointer to the parent row, as well as an optional range of child rows that is identical to the structure used for the tree.

Making the row type default constructible is optional, and allows the model to construct new row data elements, for instance in the insertRow() or moveRows() implementations.

    // tree traversal protocol implementation
    const TreeRow *parentRow() const { return m_parent; }
    const std::optional<Tree> &childRows() const { return m_children; }

The tree traversal protocol can then be implemented as member functions of the row data type. A const parentRow() function has to return a pointer to a const row item; and the childRows() function has to return a reference to a const std::optional that can hold the optional child range.

These two functions are sufficient for the model to navigate the tree as a read-only data structure. To allow the user to edit data in a view, and the model to implement mutating model APIs such as insertRows(), removeRows(), and moveRows(), we have to implement additional functions for write-access:

    void setParentRow(TreeRow *parent) { m_parent = parent; }
    std::optional<Tree> &childRows() { return m_children; }

The model calls the setParentRow() function and mutable childRows() overload to move or insert rows into an existing tree branch, and to update the parent pointer should the old value have become invalid. The non-const overload of childRows() provides in addition write-access to the row data.

    ...
    // Helper to assembly a tree of rows, not used by QGenericItemModel
    template <typename ...Args>
    TreeRow &addChild(Args &&...args)
    {
        if (!m_children)
            m_children.emplace(Tree{});
        auto &child = m_children->emplace_back(std::forward<Args>(args)...);
        child.m_parent = this;
        return child;
    }
};

The rest of the class implementation is not relevant for the model, but a addChild() helper provides us with a convenient way to construct the initial state of the tree.

Tree tree = {
    {"..."},
    {"..."},
    {"..."},
};

// each toplevel row has three children
tree[0].addChild("...");
tree[0].addChild("...");
tree[0].addChild("...");

tree[1].addChild("...");
tree[1].addChild("...");
tree[1].addChild("...");

tree[2].addChild("...");
tree[2].addChild("...");
tree[2].addChild("...");

A QGenericItemModel instantiated with an instance of such a range will represent the data as a tree.

// instantiate the model with a pointer to the tree, not a copy!
QGenericItemModel model(&tree);
QTreeView view;
view.setModel(&model);

Tree traversal protocol in a separate class

The tree traversal protocol can also be implemented in a separate class.

struct TreeTraversal
{
    TreeRow newRow() const { return TreeRow{}; }
    const TreeRow *parentRow(const TreeRow &row) const { return row.m_parent; }
    void setParentRow(TreeRow &row, TreeRow *parent) const { row.m_parent = parent; }
    const std::optional<Tree> &childRows(const TreeRow &row) const { return row.m_children; }
    std::optional<Tree> &childRows(TreeRow &row) const { return row.m_children; }
};

Pass an instance of this protocol implementation to the QGenericItemModel constructor:

QGenericItemModel model(&tree, TreeTraversal{});

Rows as pointers or values

The row type of the data range can be either a value, or a pointer. In the code above we have been using the tree rows as values in a vector, which avoids that we have to deal with explicit memory management. However, a vector as a contiguous block of memory invalidates all iterators and references when it has to reallocate the storage, or when inserting or removing elements. This impacts the pointer to the parent item, which is the location of the parent row within the vector. Making sure that this parent (and QPersistentModelIndex instances referring to items within it) stays valid can incurr substantial performance overhead. The QGenericItemModel implementation has to assume that all references into the range become invalid when modifying the range.

Alternatively, we can also use a range of row pointers as the tree type:

struct TreeRow;
using Tree = std::vector<TreeRow *>;

In this case, we have to allocate all TreeRow instances explicitly using operator new, and implement the destructor to delete all items in the vector of children.

struct TreeRow
{
    Q_GADGET
public:
    TreeRow(const QString &value = {})
        : m_value(value)
    {}
    ~TreeRow()
    {
        if (m_children)
            qDeleteAll(*m_children);
    }

    // move-only
    TreeRow(TreeRow &&) = default;
    TreeRow &operator=(TreeRow &&) = default;

    // helper to populate
    template <typename ...Args>
    TreeRow *addChild(Args &&...args)
    {
        if (!m_children)
            m_children.emplace(Tree{});
        auto *child = m_children->emplace_back(new TreeRow(std::forward<Args>(args)...));
        child->m_parent = this;
        return child;
    }

private:
    friend struct TreeTraversal;
    QString m_value;
    std::optional<Tree> m_children;
    TreeRow *m_parent = nullptr;
};
Tree tree = {
    new TreeRow("1"),
    new TreeRow("2"),
    new TreeRow("3"),
    new TreeRow("4"),
};
tree[0]->addChild("1.1");
tree[1]->addChild("2.1");
tree[2]->addChild("3.1")->addChild("3.1.1");
tree[3]->addChild("4.1");

Before we can construct a model that represents this data as a tree, we need to also implement the tree traversal protocol.

struct TreeTraversal
{
    TreeRow *newRow() const { return new TreeRow; }
    void deleteRow(TreeRow *row) { delete row; }

    const TreeRow *parentRow(const TreeRow *row) const { return row->m_parent; }
    void setParentRow(TreeRow *row, TreeRow *parent) { row->m_parent = parent; }
    const std::optional<Tree> &childRows(const TreeRow *row) const { return row->m_children; }
    std::optional<Tree> &childRows(TreeRow *row) { return row->m_children; }
};

An explicit protocol implementation for mutable trees of pointers has to provide two additional member functions, newRow() and deleteRow(RowType *).

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    Tree tree = make_tree_of_pointers();

    QGenericItemModel model(std::move(tree), TreeTraversal{});
    QTreeView treeView;
    treeView.setModel(&model);
    treeView.show();

    return app.exec();
}

The model will call those functions when creating new rows in insertRows(), and when removing rows in removeRows(). In addition, if the model has ownership of the data, then it will also delete all top-level rows upon destruction. Note how in this example, we move the tree into the model, so we must no longer perform any operations on it. QGenericItemModel, when constructed by moving tree-data with row-pointers into it, will take ownership of the data, and delete the row pointers in it's destructor.

So, using pointers at rows comes with some memory allocation and management overhead. However, when using rows through pointers the references to the row items remain stable, even when they are moved around in the range, or when the range reallocates. This can significantly reduce the cost of making modifications to the model's structure when using insertRows(), removeRows(), or moveRows().

So, each choice has different performance and memory overhead trade-offs. The best option depends on the exact use case and data structure used.

Multi-role items

The type of the items that the implementations of data(), setData(), clearItemData() etc. operate on can be the same across the entire model - like in the gridOfNumbers example above. But the range can also have different item types for different columns, like in the numberNames case.

By default, the value gets used for the Qt::DisplayRole and Qt::EditRole roles. Most views expect the value to be convertible to and from a QString (but a custom delegate might provide more flexibility).

If the item is an associative container that uses int, Qt::ItemDataRole, or QString as the key type, and QVariant as the mapped type, then QGenericItemModel interprets that container as the storage of the data for multiple roles. The data() and setData() functions return and modify the mapped value in the container, and setItemData() modifies all provided values, itemData() returns all stored values, and clearItemData() clears the entire container.

using ColorEntry = QMap<Qt::ItemDataRole, QVariant>;

const QStringList colorNames = QColor::colorNames();
QList<ColorEntry> colors;
colors.reserve(colorNames.size());
for (const QString &name : colorNames) {
    const QColor color = QColor::fromString(name);
    colors << ColorEntry{{Qt::DisplayRole, name},
                         {Qt::DecorationRole, color},
                         {Qt::ToolTipRole, color.name()}};
}
QGenericItemModel colorModel(colors);
QListView list;
list.setModel(&colorModel);

The most efficient data type to use as the key is Qt::ItemDataRole or int. When using int, itemData() returns the container as is, and doesn't have to create a copy of the data.

Gadgets and QObject types are also represented at multi-role items if they are the item type in a table. The names of the properties have to match the names of the roles.

class ColorEntry
{
    Q_GADGET
    Q_PROPERTY(QString display MEMBER m_colorName)
    Q_PROPERTY(QColor decoration READ decoration)
    Q_PROPERTY(QString toolTip READ toolTip)
public:
    ColorEntry(const QString &color = {})
        : m_colorName(color)
    {}

    QColor decoration() const
    {
        return QColor::fromString(m_colorName);
    }
    QString toolTip() const
    {
        return QColor::fromString(m_colorName).name();
    }

private:
    QString m_colorName;
};

When used in a list, these types are ambiguous: they can be represented as multi-column rows, with each property represented as a separate column. Or they can be single items with each property being a role. To disambiguate, use the QGenericItemModel::SingleColumn wrapper.

const QStringList colorNames = QColor::colorNames();
QList<QGenericItemModel::SingleColumn<ColorEntry>> colors;
colors.reserve(colorNames.size());
for (const QString &name : colorNames)
    colors << ColorEntry{name};

QGenericItemModel colorModel(colors);
QListView list;
list.setModel(&colorModel);

The C++ tuple protocol

As seen in the numberNames example above, the row type can be a tuple, and in fact any type that implements the tuple protocol. This protocol is implemented by specializing std::tuple_size and std::tuple_element, and overloading the unqualified get function. Do so for your custom row type to make existing structured data available to the model/view framework in Qt.

struct Book
{
    QString title;
    QString author;
    QString summary;
    int rating = 0;

    template <size_t I, typename T>
        requires ((I <= 3) && std::is_same_v<std::remove_cvref_t<T>, Book>)
    friend inline decltype(auto) get(T &&book)
    {
        if constexpr (I == 0)
            return std::as_const(book.title);
        else if constexpr (I == 1)
            return std::as_const(book.author);
        else if constexpr (I == 2)
            return std::forward_like<T>(book.summary);
        else if constexpr (I == 3)
            return std::forward_like<T>(book.rating);
    }
};

namespace std {
    template <> struct tuple_size<Book> : std::integral_constant<size_t, 4> {};
    template <size_t I> struct tuple_element<I, Book>
    { using type = decltype(get<I>(std::declval<Book>())); };
}

In the above implementation, the title and author values of the Book type are returned as const, so the model flags items in those two columns as read-only. The user won't be able to trigger editing, and setData() does nothing and returns false. For summary and rating the implementation returns the same value category as the book, so when get is called with a mutable reference to a Book, then it will return a mutable reference of the respective variable. The model makes those columns editable, both for the user and for programmatic access.

Types that have a meta objects, and implement the C++ tuple protocol, also can cause compile-time ambiguity when used as the row type, as the framework won't know which API to use to access the individual values. Use the QGenericItemModel::SingleColumn and QGenericItemModel::MultiColumns wrapper to disambiguate.