Revision control
Copy as Markdown
// Copyright (C) 2019 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
#include "qqmltablemodel_p.h"
#include <QtCore/qloggingcategory.h>
#include <QtQml/qqmlinfo.h>
#include <QtQml/qqmlengine.h>
QT_BEGIN_NAMESPACE
using namespace Qt::StringLiterals;
Q_STATIC_LOGGING_CATEGORY(lcTableModel, "qt.qml.tablemodel")
/*!
\qmltype TableModel
//! \nativetype QQmlTableModel
\inqmlmodule Qt.labs.qmlmodels
\brief Encapsulates a simple table model.
\since 5.14
The TableModel type stores JavaScript/JSON objects as data for a table
model that can be used with \l TableView. It is intended to support
very simple models without requiring the creation of a custom
QAbstractTableModel subclass in C++.
\snippet qml/tablemodel/fruit-example-simpledelegate.qml file
The model's initial row data is set with either the \l rows property or by
calling \l appendRow(). Each column in the model is specified by declaring
a \l TableModelColumn instance, where the order of each instance determines
its column index. Once the model's \l Component::completed() signal has been
emitted, the columns and roles will have been established and are then
fixed for the lifetime of the model.
To access a specific row, the \l getRow() function can be used.
It's also possible to access the model's JavaScript data
directly via the \l rows property, but it is not possible to
modify the model data this way.
To add new rows, use \l appendRow() and \l insertRow(). To modify
existing rows, use \l setRow(), \l moveRow(), \l removeRow(), and
\l clear().
It is also possible to modify the model's data via the delegate,
as shown in the example above:
\snippet qml/tablemodel/fruit-example-simpledelegate.qml delegate
If the type of the data at the modified role does not match the type of the
data that is set, it will be automatically converted via
\l {QVariant::canConvert()}{QVariant}.
\section1 Supported Row Data Structures
TableModel is designed to work with JavaScript/JSON data, where each row
is a list of simple key-value pairs:
\code
{
// Each property is one cell/column.
checked: false,
amount: 1,
fruitType: "Apple",
fruitName: "Granny Smith",
fruitPrice: 1.50
},
// ...
\endcode
As model manipulation in Qt is done via row and column indices,
and because object keys are unordered, each column must be specified via
TableModelColumn. This allows mapping Qt's built-in roles to any property
in each row object.
Complex row structures are supported, but with limited functionality.
As TableModel has no way of knowing how each row is structured,
it cannot manipulate it. As a consequence of this, the copy of the
model data that TableModel has stored in \l rows is not kept in sync
with the source data that was set in QML. For these reasons, manipulation
of the data is not supported.
For example, suppose you wanted to use a data source where each row is an
array and each cell is an object. To use this data source with TableModel,
define a getter:
\code
TableModel {
TableModelColumn {
display: function(modelIndex) { return rows[modelIndex.row][0].checked }
}
// ...
rows: [
[
{ checked: false, checkable: true },
{ amount: 1 },
{ fruitType: "Apple" },
{ fruitName: "Granny Smith" },
{ fruitPrice: 1.50 }
]
// ...
]
}
\endcode
The row above is one example of a complex row.
\note Row manipulation functions such as \l appendRow(), \l removeRow(),
etc. are not supported when using complex rows.
\section1 Using DelegateChooser with TableModel
For most real world use cases, it is recommended to use DelegateChooser
as the delegate of a TableView that uses TableModel. This allows you to
use specific roles in the relevant delegates. For example, the snippet
above can be rewritten to use DelegateChooser like so:
\snippet qml/tablemodel/fruit-example-delegatechooser.qml file
The most specific delegates are declared first: the columns at index \c 0
and \c 1 have \c bool and \c integer data types, so they use a
\l [QtQuickControls2]{CheckBox} and \l [QtQuickControls2]{SpinBox},
respectively. The remaining columns can simply use a
\l [QtQuickControls2]{TextField}, and so that delegate is declared
last as a fallback.
\section1 Using the TableModel with External JSON Sources
If the structure of the data in a JSON object matches the structure defined
by the TableModel, it can be assigned directly to the model using the rows
property. All rows in the data must conform to the columns defined by the model.
For example, if the model is defined as:
\snippet main.qml model
The source has the required data but not necessarily in the
required structure, you can download and parse it into a form that
conforms to the structure that the model defines and assign the result directly.
\snippet main.qml parse
and the result can be assigned directly
\snippet main.qml assign
You can also provide the JSON object by importing a JavaScript file as a
module. See the documentation for \l TreeModel for an example on how to do this.
\warning Ensure that the JSON data comes from a trusted source. Since the
model dynamically populates its rows based on the input, malformed or
untrusted JSON can lead to unexpected behavior or performance issues.
\sa TableModelColumn, TableView, QAbstractTableModel
*/
QQmlTableModel::QQmlTableModel(QObject *parent)
: QQmlAbstractColumnModel(parent)
{
}
QQmlTableModel::~QQmlTableModel()
= default;
/*!
\qmlproperty var TableModel::rows
This property holds the model data in the form of an array of rows:
\snippet qml/tablemodel/fruit-example-simpledelegate.qml rows
\sa getRow(), setRow(), moveRow(), appendRow(), insertRow(), clear(), rowCount, columnCount
*/
QVariant QQmlTableModel::rows() const
{
return mRows;
}
void QQmlTableModel::setRows(const QVariant &rows)
{
const std::optional<QVariantList> validated = validateRowsArgument(rows);
if (!validated)
return;
const QVariantList rowsAsVariantList = *validated;
if (rowsAsVariantList == mRows) {
// No change.
return;
}
if (!mComponentCompleted) {
// Store the rows until we can call setRowsPrivate() after component completion.
mRows = rowsAsVariantList;
return;
}
setRowsPrivate(rowsAsVariantList);
}
void QQmlTableModel::setRowsPrivate(const QVariantList &rowsAsVariantList)
{
Q_ASSERT(mComponentCompleted);
// By now, all TableModelColumns should have been set.
if (mColumns.isEmpty()) {
qmlWarning(this) << "No TableModelColumns were set; model will be empty";
return;
}
const bool firstTimeValidRowsHaveBeenSet = mColumnMetadata.isEmpty();
if (!firstTimeValidRowsHaveBeenSet) {
// This is not the first time rows have been set; validate each one.
for (int rowIndex = 0; rowIndex < rowsAsVariantList.size(); ++rowIndex) {
// validateNewRow() expects a QVariant wrapping a QJSValue, so to
// simplify the code, just create one here.
const QVariant row = QVariant::fromValue(rowsAsVariantList.at(rowIndex));
if (!validateNewRow("setRows()"_L1, row, SetRowsOperation))
return;
}
}
const int oldRowCount = mRowCount;
beginResetModel();
// We don't clear the column or role data, because a TableModel should not be reused in that way.
// Once it has valid data, its columns and roles are fixed.
mRows = rowsAsVariantList;
mRowCount = mRows.size();
// Gather metadata the first time rows is set.
if (firstTimeValidRowsHaveBeenSet && !mRows.isEmpty())
fetchColumnMetadata();
endResetModel();
emit rowsChanged();
if (mRowCount != oldRowCount)
emit rowCountChanged();
}
QVariant QQmlTableModel::dataPrivate(const QModelIndex &index, const QString &roleName) const
{
const ColumnMetadata columnMetadata = mColumnMetadata.at(index.column());
const QString propertyName = columnMetadata.roles.value(roleName).name;
const QVariantMap rowData = mRows.at(index.row()).toMap();
return rowData.value(propertyName);
}
void QQmlTableModel::setDataPrivate(const QModelIndex &index, const QString &roleName, QVariant value)
{
int row = index.row();
QVariantMap modifiedRow = mRows.at(row).toMap();
modifiedRow[roleName] = value;
mRows[row] = modifiedRow;
}
// TODO: Turn this into a snippet that compiles in CI
/*!
\qmlmethod void TableModel::appendRow(var row)
Adds a new row to the end of the model, with the
values (cells) in \a row.
\code
model.appendRow({
checkable: true,
amount: 1,
fruitType: "Pear",
fruitName: "Williams",
fruitPrice: 1.50,
})
\endcode
\sa insertRow(), setRow(), removeRow()
*/
void QQmlTableModel::appendRow(const QVariant &row)
{
if (!validateNewRow("appendRow()"_L1, row, AppendOperation))
return;
doInsert(mRowCount, row);
}
/*!
\qmlmethod void TableModel::clear()
Removes all rows from the model.
\sa removeRow()
*/
void QQmlTableModel::clear()
{
if (mRows.empty())
return;
beginResetModel();
mRows.clear();
mRowCount = 0;
endResetModel();
emit rowCountChanged();
emit rowsChanged();
}
/*!
\qmlmethod var TableModel::getRow(int rowIndex)
Returns the row at \a rowIndex in the model.
Note that this equivalent to accessing the row directly
through the \l rows property:
\code
Component.onCompleted: {
// These two lines are equivalent.
console.log(model.getRow(0).display);
console.log(model.rows[0].fruitName);
}
\endcode
\note the returned object cannot be used to modify the contents of the
model; use setRow() instead.
\sa setRow(), appendRow(), insertRow(), removeRow(), moveRow()
*/
QVariant QQmlTableModel::getRow(int rowIndex)
{
if (!validateRowIndex("getRow()"_L1, "rowIndex"_L1, rowIndex, NeedsExisting))
return QVariant();
return mRows.at(rowIndex);
}
/*!
\qmlmethod void TableModel::insertRow(int rowIndex, var row)
Adds a new row to the model at position \a rowIndex, with the
values (cells) in \a row.
\code
model.insertRow(2, {
checkable: true, checked: false,
amount: 1,
fruitType: "Pear",
fruitName: "Williams",
fruitPrice: 1.50,
})
\endcode
The \a rowIndex must point to an existing item in the table, or one past
the end of the table (equivalent to \l appendRow()).
\sa appendRow(), setRow(), removeRow(), rowCount
*/
void QQmlTableModel::insertRow(int rowIndex, const QVariant &row)
{
if (!validateNewRow("insertRow()"_L1, row) ||
!validateRowIndex("insertRow()"_L1, "rowIndex"_L1, rowIndex, CanAppend))
return;
doInsert(rowIndex, row);
}
void QQmlTableModel::doInsert(int rowIndex, const QVariant &row)
{
beginInsertRows(QModelIndex(), rowIndex, rowIndex);
// Adding rowAsVariant.toList() will add each invidual variant in the list,
// which is definitely not what we want.
const QVariant rowAsVariant = row.userType() == QMetaType::QVariantMap ? row : row.value<QJSValue>().toVariant();
mRows.insert(rowIndex, rowAsVariant);
++mRowCount;
qCDebug(lcTableModel).nospace() << "inserted the following row to the model at index "
<< rowIndex << ":\n" << rowAsVariant.toMap();
// Gather metadata the first time a row is added.
if (mColumnMetadata.isEmpty())
fetchColumnMetadata();
endInsertRows();
emit rowCountChanged();
emit rowsChanged();
}
/*!
\qmlmethod void TableModel::moveRow(int fromRowIndex, int toRowIndex, int rows)
Moves \a rows from the index at \a fromRowIndex to the index at
\a toRowIndex.
The from and to ranges must exist; for example, to move the first 3 items
to the end of the list:
\code
model.moveRow(0, model.rowCount - 3, 3)
\endcode
\sa appendRow(), insertRow(), removeRow(), rowCount
*/
void QQmlTableModel::moveRow(int fromRowIndex, int toRowIndex, int rows)
{
if (fromRowIndex == toRowIndex) {
qmlWarning(this) << "moveRow(): \"fromRowIndex\" cannot be equal to \"toRowIndex\"";
return;
}
if (rows <= 0) {
qmlWarning(this) << "moveRow(): \"rows\" is less than or equal to 0";
return;
}
if (!validateRowIndex("moveRow()"_L1, "fromRowIndex"_L1, fromRowIndex, NeedsExisting))
return;
if (!validateRowIndex("moveRow()"_L1, "toRowIndex"_L1, toRowIndex, NeedsExisting))
return;
if (fromRowIndex + rows > mRowCount) {
qmlWarning(this) << "moveRow(): \"fromRowIndex\" (" << fromRowIndex
<< ") + \"rows\" (" << rows << ") = " << (fromRowIndex + rows)
<< ", which is greater than rowCount() of " << mRowCount;
return;
}
if (toRowIndex + rows > mRowCount) {
qmlWarning(this) << "moveRow(): \"toRowIndex\" (" << toRowIndex
<< ") + \"rows\" (" << rows << ") = " << (toRowIndex + rows)
<< ", which is greater than rowCount() of " << mRowCount;
return;
}
qCDebug(lcTableModel).nospace() << "moving " << rows
<< " row(s) from index " << fromRowIndex
<< " to index " << toRowIndex;
// Based on the same call in QQmlListModel::moveRow().
beginMoveRows(QModelIndex(), fromRowIndex, fromRowIndex + rows - 1, QModelIndex(),
toRowIndex > fromRowIndex ? toRowIndex + rows : toRowIndex);
// Based on ListModel::moveRow().
if (fromRowIndex > toRowIndex) {
// Only move forwards - flip if moving backwards.
const int from = fromRowIndex;
const int to = toRowIndex;
fromRowIndex = to;
toRowIndex = to + rows;
rows = from - to;
}
QList<QVariant> store;
store.reserve(rows);
for (int i = 0; i < (toRowIndex - fromRowIndex); ++i)
store.append(mRows.at(fromRowIndex + rows + i));
for (int i = 0; i < rows; ++i)
store.append(mRows.at(fromRowIndex + i));
for (int i = 0; i < store.size(); ++i)
mRows[fromRowIndex + i] = store[i];
qCDebug(lcTableModel).nospace() << "after moving, rows are:\n" << mRows;
endMoveRows();
emit rowsChanged();
}
/*!
\qmlmethod void TableModel::removeRow(int rowIndex, int rows = 1)
Removes a number of \a rows at \a rowIndex from the model.
\sa clear(), rowCount
*/
void QQmlTableModel::removeRow(int rowIndex, int rows)
{
if (!validateRowIndex("removeRow()"_L1, "rowIndex"_L1, rowIndex, NeedsExisting))
return;
if (rows <= 0) {
qmlWarning(this) << "removeRow(): \"rows\" is less than or equal to zero";
return;
}
if (rowIndex + rows - 1 >= mRowCount) {
qmlWarning(this) << "removeRow(): \"rows\" " << rows
<< " exceeds available rowCount() of " << mRowCount
<< " when removing from \"rowIndex\" " << rowIndex;
return;
}
beginRemoveRows(QModelIndex(), rowIndex, rowIndex + rows - 1);
auto firstIterator = mRows.begin() + rowIndex;
// The "last" argument to erase() is exclusive, so we go one past the last item.
auto lastIterator = firstIterator + rows;
mRows.erase(firstIterator, lastIterator);
mRowCount -= rows;
endRemoveRows();
emit rowCountChanged();
emit rowsChanged();
qCDebug(lcTableModel).nospace() << "removed " << rows
<< " items from the model, starting at index " << rowIndex;
}
/*!
\qmlmethod void TableModel::setRow(int rowIndex, var row)
Changes the row at \a rowIndex in the model with \a row.
All columns/cells must be present in \c row, and in the correct order.
\code
model.setRow(0, {
checkable: true,
amount: 1,
fruitType: "Pear",
fruitName: "Williams",
fruitPrice: 1.50,
})
\endcode
If \a rowIndex is equal to \c rowCount(), then a new row is appended to the
model. Otherwise, \a rowIndex must point to an existing row in the model.
\sa appendRow(), insertRow(), rowCount
*/
void QQmlTableModel::setRow(int rowIndex, const QVariant &row)
{
if (!validateNewRow("setRow()"_L1, row) ||
!validateRowIndex("setRow()"_L1, "rowIndex"_L1, rowIndex, CanAppend))
return;
if (rowIndex != mRowCount) {
// Setting an existing row.
mRows[rowIndex] = row;
// For now we just assume the whole row changed, as it's simpler.
const QModelIndex topLeftModelIndex(createIndex(rowIndex, 0));
const QModelIndex bottomRightModelIndex(createIndex(rowIndex, mColumnCount - 1));
emit dataChanged(topLeftModelIndex, bottomRightModelIndex);
emit rowsChanged();
} else {
// Appending a row.
doInsert(rowIndex, row);
}
}
QVariant QQmlTableModel::firstRow() const
{
return mRows.first();
}
void QQmlTableModel::setInitialRows()
{
setRowsPrivate(mRows);
}
/*!
\qmlmethod QModelIndex TableModel::index(int row, int column)
Returns a \l QModelIndex object referencing the given \a row and \a column,
which can be passed to the data() function to get the data from that cell,
or to setData() to edit the contents of that cell.
\code
import QtQml 2.14
import Qt.labs.qmlmodels 1.0
TableModel {
id: model
TableModelColumn { display: "fruitType" }
TableModelColumn { display: "fruitPrice" }
rows: [
{ fruitType: "Apple", fruitPrice: 1.50 },
{ fruitType: "Orange", fruitPrice: 2.50 }
]
Component.onCompleted: {
for (var r = 0; r < model.rowCount; ++r) {
console.log("An " + model.data(model.index(r, 0)).display +
" costs " + model.data(model.index(r, 1)).display.toFixed(2))
}
}
}
\endcode
\sa {QModelIndex and related Classes in QML}, data()
*/
// Note: we don't document the parent argument, because you never need it, because
// cells in a TableModel don't have parents. But it is there because this function is an override.
QModelIndex QQmlTableModel::index(int row, int column, const QModelIndex &parent) const
{
return row >= 0 && row < rowCount() && column >= 0 && column < columnCount() && !parent.isValid()
? createIndex(row, column)
: QModelIndex();
}
QModelIndex QQmlTableModel::parent(const QModelIndex &index) const
{
Q_UNUSED(index);
return {};
}
/*!
\qmlproperty int TableModel::rowCount
\readonly
This read-only property holds the number of rows in the model.
This value changes whenever rows are added or removed from the model.
*/
int QQmlTableModel::rowCount(const QModelIndex &parent) const
{
if (parent.isValid())
return 0;
return mRowCount;
}
/*!
\qmlproperty int TableModel::columnCount
\readonly
This read-only property holds the number of columns in the model.
The number of columns is fixed for the lifetime of the model
after the \l rows property is set or \l appendRow() is called for the first
time.
*/
int QQmlTableModel::columnCount(const QModelIndex &parent) const
{
Q_UNUSED(parent);
return mColumnCount;
}
/*!
\qmlmethod variant TableModel::data(QModelIndex index, string role)
Returns the data from the table cell at the given \a index belonging to the
given \a role.
\sa index(), setData()
*/
/*!
\qmlmethod bool TableModel::setData(QModelIndex index, variant value, string role)
Inserts or updates the data field named by \a role in the table cell at the
given \a index with \a value. Returns true if successful, false if not.
\sa data(), index()
*/
bool QQmlTableModel::validateRowIndex(QLatin1StringView functionName, QLatin1StringView argumentName,
int rowIndex, RowOption operation) const
{
if (rowIndex < 0) {
qmlWarning(this).noquote() << functionName << ": \"" << argumentName << "\" cannot be negative";
return false;
}
if (operation == NeedsExisting) {
if (rowIndex >= mRowCount) {
qmlWarning(this).noquote() << functionName << ": \"" << argumentName
<< "\" " << rowIndex << " is greater than or equal to rowCount() of " << mRowCount;
return false;
}
} else {
if (rowIndex > mRowCount) {
qmlWarning(this).noquote() << functionName << ": \"" << argumentName
<< "\" " << rowIndex << " is greater than rowCount() of " << mRowCount;
return false;
}
}
return true;
}
QT_END_NAMESPACE
#include "moc_qqmltablemodel_p.cpp"