QModelRoleDataSpan 类

The QModelRoleDataSpan class provides a span over QModelRoleData 对象。 更多...

头: #include <QModelRoleDataSpan>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Since: Qt 6.0

公共函数

QModelRoleDataSpan ()
QModelRoleDataSpan (QModelRoleData & modelRoleData )
QModelRoleDataSpan (QModelRoleData * modelRoleData , qsizetype len )
QModelRoleDataSpan (Container & c )
QModelRoleData * begin () const
QModelRoleData * data () const
QVariant * dataForRole (int role ) const
QModelRoleData * end () const
qsizetype length () const
qsizetype size () const
QModelRoleData & operator[] (qsizetype index ) const

详细描述

A QModelRoleDataSpan is used as an abstraction over an array of QModelRoleData 对象。

Like a view, QModelRoleDataSpan provides a small object (pointer and size) that can be passed to functions that need to examine the contents of the array. A QModelRoleDataSpan can be constructed from any array-like sequence (plain arrays, QVector , std::vector, QVarLengthArray , and so on). Moreover, it does not own the sequence, which must therefore be kept alive longer than any QModelRoleDataSpan objects referencing it.

Unlike a view, QModelRoleDataSpan is a span, so it allows for modifications to the underlying elements.

QModelRoleDataSpan's main use case is making it possible for a model to return the data corresponding to different roles in one call.

In order to draw one element from a model, a view (through its delegates) will generally request multiple roles for the same index by calling data() as many times as needed:

QVariant text = model->data(index, Qt::DisplayRole);
QVariant decoration = model->data(index, Qt::DecorationRole);
QVariant checkState = model->data(index, Qt::CheckStateRole);
// etc.
					

QModelRoleDataSpan allows a view to request the same data using just one function call.

This is achieved by having the view prepare a suitable array of QModelRoleData objects, each initialized with the role that should be fetched. The array is then wrapped in a QModelRoleDataSpan object, which is then passed to a model's multiData() 函数。

std::array<QModelRoleData, 3> roleData = { {
    QModelRoleData(Qt::DisplayRole),
    QModelRoleData(Qt::DecorationRole),
    QModelRoleData(Qt::CheckStateRole)
} };
// Usually, this is not necessary: A QModelRoleDataSpan
// will be built automatically for you when passing an array-like
// container to multiData().
QModelRoleDataSpan span(roleData);
model->multiData(index, span);
// Use roleData[0].data(), roleData[1].data(), etc.
					

Views are encouraged to store the array of QModelRoleData objects (and, possibly, the corresponding span) and re-use it in subsequent calls to the model. This allows to reduce the memory allocations related with creating and returning QVariant 对象。

Finally, given a QModelRoleDataSpan object, the model's responsibility is to fill in the data corresponding to each role in the span. How this is done depends on the concrete model class. Here's a sketch of a possible implementation that iterates over the span and uses setData() on each element:

void MyModel::multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const
{
    for (QModelRoleData &roleData : roleDataSpan) {
        int role = roleData.role();
        // ... obtain the data for index and role ...
        roleData.setData(result);
    }
}
					

另请参阅 模型/视图编程 and QAbstractItemModel::multiData ().

成员函数文档编制

[constexpr noexcept] QModelRoleDataSpan:: QModelRoleDataSpan ()

Constructs an empty QModelRoleDataSpan. Its data () 会被设为 nullptr , and its length to zero.

[constexpr noexcept] QModelRoleDataSpan:: QModelRoleDataSpan ( QModelRoleData & modelRoleData )

Constructs an QModelRoleDataSpan spanning over modelRoleData , seen as a 1-element array.

[constexpr] QModelRoleDataSpan:: QModelRoleDataSpan ( QModelRoleData * modelRoleData , qsizetype len )

Constructs an QModelRoleDataSpan spanning over the array beginning at modelRoleData and with length len .

注意: The array must be kept alive as long as this object has not been destructed.

[constexpr noexcept(...)] template <typename Container, QModelRoleDataSpan::if_compatible_container<Container> = true> QModelRoleDataSpan:: QModelRoleDataSpan ( Container & c )

Constructs an QModelRoleDataSpan spanning over the container c , which can be any contiguous container of QModelRoleData objects. For instance, it can be a QVector<QModelRoleData> std::array<QModelRoleData, 10> and so on.

注意: The container must be kept alive as long as this object has not been destructed.

注意: This function does not throw any exception when "noexcept(std::data(c)) && noexcept(std::size(c))" is true.

[constexpr noexcept] QModelRoleData *QModelRoleDataSpan:: begin () const

Returns a pointer to the beginning of the span represented by this object.

[constexpr noexcept] QModelRoleData *QModelRoleDataSpan:: data () const

Returns a pointer to the beginning of the span represented by this object.

[constexpr] QVariant *QModelRoleDataSpan:: dataForRole ( int role ) const

Returns the data associated with the first QModelRoleData in the span that has its role equal to role . If such a QModelRoleData object does not exist, the behavior is undefined.

注意: Avoid calling this function from the model's side, as a model cannot possibly know in advance which roles are in a given QModelRoleDataSpan . This function is instead suitable for views and delegates, which have control over the roles in the span.

另请参阅 QModelRoleData::data ().

[constexpr noexcept] QModelRoleData *QModelRoleDataSpan:: end () const

Returns a pointer to the imaginary element one past the end of the span represented by this object.

[constexpr noexcept] qsizetype QModelRoleDataSpan:: length () const

Returns the length of the span represented by this object.

[constexpr noexcept] qsizetype QModelRoleDataSpan:: size () const

Returns the length of the span represented by this object.

[constexpr] QModelRoleData &QModelRoleDataSpan:: operator[] ( qsizetype index ) const

Returns a modifiable reference to the QModelRoleData 在位置 index in the span.

注意: index must be a valid index for this span (0 <= index < size ()).