QRangeModel Class

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

QRangeModel model(numbers);

QRangeModel model(&numbers);

QRangeModel model(std::ref(numbers));

auto shared_numbers = std::make_shared<std::vector<int>>(numbers);
QRangeModel model(shared_numbers);

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

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

QRangeModel model(std::cref(numbers));

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

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

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

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 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()}};
}
QRangeModel colorModel(colors);
QListView list;
list.setModel(&colorModel);

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;
};

QList<QList<ColorEntry>> colorTable;

// ...

QRangeModel colorModel(colorTable);
QTableView table;
table.setModel(&colorModel);

class ColorEntry
{
    Q_GADGET
    Q_PROPERTY(QString display MEMBER m_colorName)
    Q_PROPERTY(QColor decoration READ decoration)
    Q_PROPERTY(QString toolTip READ toolTip)
public:
    ...
};
template <>
struct QRangeModel::RowOptions<ColorEntry>
{
    static constexpr auto rowCategory = QRangeModel::RowCategory::MultiRoleItem;
};

const QStringList colorNames = QColor::colorNames();
QList<std::tuple<ColorEntry>> colors;

// ...

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

ColorEntry firstEntry = std::get<0>(colors.at(0));

auto [firstEntry] = colors.at(0);

class Entry : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString display READ display WRITE setDisplay NOTIFY displayChanged)
    Q_PROPERTY(QIcon decoration READ decoration WRITE setDecoration NOTIFY decorationChanged)
    Q_PROPERTY(QString toolTip READ toolTip WRITE setToolTip NOTIFY toolTipChanged)

public:
    Entry() = default;

    QString display() const
    {
        return m_display;
    }

    void setDisplay(const QString &display)
    {
        if (m_display == display)
            return;
        m_display = display;
        emit displayChanged(m_display);
    }

signals:
    void displayChanged(const QString &);
    ...
};
std::vector<std::shared_ptr<Entry>> entries = {
    ...
};
QRangeModel model(std::ref(entries));
QListView listView;
listView.setModel(&model);

template <>
struct QRangeModel::RowOptions<Entry>
{
    static constexpr auto rowCategory = QRangeModel::RowCategory::MultiRoleItem;
};
std::vector<std::shared_ptr<Entry>> entries = {
    std::make_shared<Entry>(),
    ...
};

QRangeModel model(std::ref(entries));

class NumbersModel : public QRangeModel
{
    std::vector<int> m_numbers;

public:
    NumbersModel(const std::vector<int> &numbers)
        : QRangeModel(std::ref(m_numbers))
        , m_numbers(numbers)
    {
    }

    void setNumber(int idx, int number)
    {
        setData(index(idx, 0), QVariant::fromValue(number));
    }

    int number(int idx) const
    {
        return m_numbers.at(idx);
    }
};

class TreeRow;

using Tree = std::vector<TreeRow>;

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

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

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

    ...
    // Helper to assembly a tree of rows, not used by QRangeModel
    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;
    }
};

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("...");

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

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; }
};

QRangeModel model(&tree, TreeTraversal{});

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

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");

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; }
};

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

    Tree tree = make_tree_of_pointers();

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

    return app.exec();
}

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>())); };
}

Member Function Documentation

Constructs a QRangeModel instance that operates on the data in range. The range has to be a sequential range for which std::begin and std::end are available. If protocol is provided, then the model will represent the range as a tree using the protocol implementation. The model instance becomes a child of parent.

The range can be a pointer or reference wrapper, in which case mutating model APIs (such as setData() or insertRow()) will modify the data in the referenced range instance. If range is a value (or moved into the model), then connect to the signals emitted by the model to respond to changes to the data.

QRangeModel will not access the range while being constructed. This makes it legal to pass a pointer or reference to a range object that is not fully constructed yet to this constructor, for example when subclassing QRangeModel.

If the range was moved into the model, then the range and all data in it will be destroyed upon destruction of the model.

[override virtual noexcept] QRangeModel::~QRangeModel()

Destroys the QRangeModel.

The range that the model was constructed from is not accessed, and only destroyed if the model was constructed from a moved-in range.

[override virtual] QModelIndex QRangeModel::buddy(const QModelIndex &index) const

Reimplements: QAbstractItemModel::buddy(const QModelIndex &index) const.

[override virtual] bool QRangeModel::canDropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) const

Reimplements: QAbstractItemModel::canDropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) const.

[override virtual] bool QRangeModel::canFetchMore(const QModelIndex &parent) const

Reimplements: QAbstractItemModel::canFetchMore(const QModelIndex &parent) const.

[override virtual] bool QRangeModel::clearItemData(const QModelIndex &index)

Reimplements: QAbstractItemModel::clearItemData(const QModelIndex &index).

Replaces the value stored in the range at index with a default- constructed value.

For models operating on a read-only range, or on a read-only column in a row type that implements the C++ tuple protocol, this implementation returns false immediately.

[override virtual] int QRangeModel::columnCount(const QModelIndex &parent = {}) const

Reimplements: QAbstractItemModel::columnCount(const QModelIndex &parent) const.

Returns the number of columns of the model. This function returns the same value for all parent indexes.

For models operating on a statically sized row type, this returned value is always the same throughout the lifetime of the model. For models operating on dynamically sized row type, the model returns the number of items in the first row, or 0 if the model has no rows.

See also rowCount and insertColumns().

[override virtual] QVariant QRangeModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const

Reimplements: QAbstractItemModel::data(const QModelIndex &index, int role) const.

Returns the data stored under the given role for the value in the range referred to by the index.

If the item type for that index is an associative container that maps from either int, Qt::ItemDataRole, or QString to a QVariant, then the role data is looked up in that container and returned.

If the item is a gadget or QObject, then the implementation returns the value of the item's property matching the role entry in the roleNames() mapping.

Otherwise, the implementation returns a QVariant constructed from the item via QVariant::fromValue() for Qt::DisplayRole or Qt::EditRole. For other roles, the implementation returns an invalid (default-constructed) QVariant.

See also Qt::ItemDataRole, setData(), and headerData().

[override virtual] bool QRangeModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)

Reimplements: QAbstractItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent).

[override virtual protected] bool QRangeModel::event(QEvent *event)

Reimplements: QObject::event(QEvent *e).

[override virtual protected] bool QRangeModel::eventFilter(QObject *object, QEvent *event)

Reimplements: QObject::eventFilter(QObject *watched, QEvent *event).

[override virtual] void QRangeModel::fetchMore(const QModelIndex &parent)

Reimplements: QAbstractItemModel::fetchMore(const QModelIndex &parent).

[override virtual] Qt::ItemFlags QRangeModel::flags(const QModelIndex &index) const

Reimplements: QAbstractItemModel::flags(const QModelIndex &index) const.

Returns the item flags for the given index.

The implementation returns a combination of flags that enables the item (ItemIsEnabled) and allows it to be selected (ItemIsSelectable). For models operating on a range with mutable data, it also sets the flag that allows the item to be editable (ItemIsEditable).

See also Qt::ItemFlags.

[override virtual] bool QRangeModel::hasChildren(const QModelIndex &parent = QModelIndex()) const

Reimplements: QAbstractItemModel::hasChildren(const QModelIndex &parent) const.

[override virtual] QVariant QRangeModel::headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const

Reimplements: QAbstractItemModel::headerData(int section, Qt::Orientation orientation, int role) const.

Returns the data for the given role and section in the header with the specified orientation.

For horizontal headers, the section number corresponds to the column number. Similarly, for vertical headers, the section number corresponds to the row number.

For the horizontal header and the Qt::DisplayRole role, models that operate on a range that uses an array as the row type return section. If the row type is a tuple, then the implementation returns the name of the type at section. For rows that are a gadget or QObject type, this function returns the name of the property at the index of section.

For the vertical header, this function always returns the result of the default implementation in QAbstractItemModel.

See also Qt::ItemDataRole, setHeaderData(), and QHeaderView.

[override virtual] QModelIndex QRangeModel::index(int row, int column, const QModelIndex &parent = {}) const

Reimplements: QAbstractItemModel::index(int row, int column, const QModelIndex &parent) const.

Returns the index of the model item at row and column in parent.

Passing a valid parent produces an invalid index for models that operate on list and table ranges.

See also parent().

[override virtual] bool QRangeModel::insertColumns(int column, int count, const QModelIndex &parent = {})

Reimplements: QAbstractItemModel::insertColumns(int column, int count, const QModelIndex &parent).

Inserts count empty columns before the item at column in all rows of the range at parent. Returns true if successful; otherwise returns false.

For models operating on a read-only range, or on a range with a statically sized row type (such as a tuple, array, or struct), this implementation does nothing and returns false immediately. This is always the case for tree models.

[override virtual] bool QRangeModel::insertRows(int row, int count, const QModelIndex &parent = {})

Reimplements: QAbstractItemModel::insertRows(int row, int count, const QModelIndex &parent).

Inserts count empty rows before the given row into the range at parent. Returns true if successful; otherwise returns false.

For models operating on a read-only or statically-sized range (such as an array), this implementation does nothing and returns false immediately.

[override virtual] QMap<int, QVariant> QRangeModel::itemData(const QModelIndex &index) const

Reimplements: QAbstractItemModel::itemData(const QModelIndex &index) const.

Returns a map with values for all predefined roles in the model for the item at the given index.

If the item type for that index is an associative container that maps from either int, Qt::ItemDataRole, or QString to a QVariant, then the data from that container is returned.

If the item type is a gadget or QObject subclass, then the values of those properties that match a role name are returned.

If the item is not an associative container, gadget, or QObject subclass, then this calls the base class implementation.

See also setItemData(), Qt::ItemDataRole, and data().

[override virtual] QModelIndexList QRangeModel::match(const QModelIndex &start, int role, const QVariant &value, int hits, Qt::MatchFlags flags) const

Reimplements: QAbstractItemModel::match(const QModelIndex &start, int role, const QVariant &value, int hits, Qt::MatchFlags flags) const.

[override virtual] QMimeData *QRangeModel::mimeData(const QModelIndexList &indexes) const

Reimplements: QAbstractItemModel::mimeData(const QModelIndexList &indexes) const.

[override virtual] QStringList QRangeModel::mimeTypes() const

Reimplements: QAbstractItemModel::mimeTypes() const.

[override virtual] bool QRangeModel::moveColumns(const QModelIndex &sourceParent, int sourceColumn, int count, const QModelIndex &destinationParent, int destinationColumn)

Reimplements: QAbstractItemModel::moveColumns(const QModelIndex &sourceParent, int sourceColumn, int count, const QModelIndex &destinationParent, int destinationChild).

Moves count columns starting with the given sourceColumn under parent sourceParent to column destinationColumn under parent destinationParent.

Returns true if the columns were successfully moved; otherwise returns false.

[override virtual] bool QRangeModel::moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationRow)

Reimplements: QAbstractItemModel::moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild).

Moves count rows starting with the given sourceRow under parent sourceParent to row destinationRow under parent destinationParent.

Returns true if the rows were successfully moved; otherwise returns false.

[override virtual] void QRangeModel::multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const

Reimplements: QAbstractItemModel::multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const.

[override virtual] QModelIndex QRangeModel::parent(const QModelIndex &child) const

Reimplements: QAbstractItemModel::parent(const QModelIndex &index) const.

Returns the parent of the item at the child index.

This function always produces an invalid index for models that operate on list and table ranges. For models operation on a tree, this function returns the index for the row item returned by the parent() implementation of the tree traversal protocol.

See also index() and hasChildren().

[override virtual] bool QRangeModel::removeColumns(int column, int count, const QModelIndex &parent = {})

Reimplements: QAbstractItemModel::removeColumns(int column, int count, const QModelIndex &parent).

Removes count columns from the item at column on in all rows of the range at parent. Returns true if successful, otherwise returns false.

For models operating on a read-only range, or on a range with a statically sized row type (such as a tuple, array, or struct), this implementation does nothing and returns false immediately. This is always the case for tree models.

[override virtual] bool QRangeModel::removeRows(int row, int count, const QModelIndex &parent = {})

Reimplements: QAbstractItemModel::removeRows(int row, int count, const QModelIndex &parent).

Removes count rows from the range at parent, starting with the given row. Returns true if successful, otherwise returns false.

For models operating on a read-only or statically-sized range (such as an array), this implementation does nothing and returns false immediately.

[override virtual protected slot] void QRangeModel::resetInternalData()

Reimplements: QAbstractItemModel::resetInternalData().

[override virtual] QHash<int, QByteArray> QRangeModel::roleNames() const

Reimplements: QAbstractItemModel::roleNames() const.

See also setRoleNames().

[override virtual] int QRangeModel::rowCount(const QModelIndex &parent = {}) const

Reimplements: QAbstractItemModel::rowCount(const QModelIndex &parent) const.

Returns the number of rows under the given parent. This is the number of items in the root range for an invalid parent index.

If the parent index is valid, then this function always returns 0 for models that operate on list and table ranges. For trees, this returns the size of the range returned by the childRows() implementation of the tree traversal protocol.

See also columnCount(), insertRows(), and hasChildren().

[override virtual] bool QRangeModel::setData(const QModelIndex &index, const QVariant &data, int role = Qt::EditRole)

Reimplements: QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value, int role).

Sets the role data for the item at index to data.

If the item type for that index is an associative container that maps from either int, Qt::ItemDataRole, or QString to a QVariant, then data is stored in that container for the key specified by role.

If the item is a gadget or QObject, then data is written to the item's property matching the role entry in the the roleNames() mapping. The function returns true if a property was found and if data stored a value that could be converted to the required type, otherwise returns false.

Otherwise, this implementation assigns the value in data to the item at the index in the range for Qt::DisplayRole and Qt::EditRole, and returns true. For other roles, the implementation returns false.

For models operating on a read-only range, or on a read-only column in a row type that implements the C++ tuple protocol, this implementation returns false immediately.

See also data().

[override virtual] bool QRangeModel::setHeaderData(int section, Qt::Orientation orientation, const QVariant &data, int role = Qt::EditRole)

Reimplements: QAbstractItemModel::setHeaderData(int section, Qt::Orientation orientation, const QVariant &value, int role).

See also headerData().

[override virtual] bool QRangeModel::setItemData(const QModelIndex &index, const QMap<int, QVariant> &data)

Reimplements: QAbstractItemModel::setItemData(const QModelIndex &index, const QMap<int, QVariant> &roles).

If the item type for that index is an associative container that maps from either int or Qt::ItemDataRole to a QVariant, then the entries in data are stored in that container. If the associative container maps from QString to QVariant, then only those values in data are stored for which there is a mapping in the role names table.

If the item type is a gadget or QObject subclass, then those properties that match a role name are set to the corresponding value in data.

Roles for which there is no entry in data are not modified.

For item types that can be copied, this implementation is transactional, and returns true if all the entries from data could be stored. If any entry could not be updated, then the original container is not modified at all, and the function returns false.

If the item is not an associative container, gadget, or QObject subclass, then this calls the base class implementation, which calls setData() for each entry in data.

See also itemData(), setData(), and Qt::ItemDataRole.

[override virtual] QModelIndex QRangeModel::sibling(int row, int column, const QModelIndex &index) const

Reimplements: QAbstractItemModel::sibling(int row, int column, const QModelIndex &index) const.

Returns the sibling at row and column for the item at index, or an invalid QModelIndex if there is no sibling at that location.

This implementation is significantly faster than going through the parent() of the index.

See also index(), QModelIndex::row(), and QModelIndex::column().

[override virtual] void QRangeModel::sort(int column, Qt::SortOrder order = Qt::AscendingOrder)

Reimplements: QAbstractItemModel::sort(int column, Qt::SortOrder order).

[override virtual] QSize QRangeModel::span(const QModelIndex &index) const

Reimplements: QAbstractItemModel::span(const QModelIndex &index) const.

[override virtual] Qt::DropActions QRangeModel::supportedDragActions() const

Reimplements: QAbstractItemModel::supportedDragActions() const.

[override virtual] Qt::DropActions QRangeModel::supportedDropActions() const

Reimplements: QAbstractItemModel::supportedDropActions() const.