Класс QModelRoleDataSpan

Класс QModelRoleDataSpan предоставляет диапазон объектов QModelRoleData. Подробнее...

• Список всех членов, включая унаследованные

Открытые функции

Подробное описание

QModelRoleDataSpan используется как абстракция над массивом объектов QModelRoleData.

Подобно представлению, QModelRoleDataSpan предоставляет небольшой объект (указатель и размер), который можно передавать функциям, которым нужно проверить содержимое массива. QModelRoleDataSpan можно создать из любого похожей на массив последовательности (простых массивов, QVector, std::vector, QVarLengthArray и т. д.). Кроме того, он не владеет последовательностью, поэтому она должна существовать дольше, чем любые объекты QModelRoleDataSpan, ссылающиеся на нее.

В отличие от представления, QModelRoleDataSpan — это диапазон, поэтому он позволяет изменять подлежащие элементы.

Основное применение QModelRoleDataSpan заключается в возможности для модели возвращать данные, соответствующие различным ролям, в одном вызове.

Для того, чтобы отобразить один элемент из модели, представление (через своих делегатов) обычно запрашивает несколько ролей для одного и того же индекса, вызывая data() столько раз, сколько нужно:

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

QModelRoleDataSpan позволяет представлению запросить те же данные с помощью одного вызова функции.

Это достигается тем, что представление подготавливает подходящий массив объектов QModelRoleData, каждый из которых инициализирован ролью, которая должна быть извлечена. Массив затем обернут в объект QModelRoleDataSpan, который затем передается в функцию 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.

Представлениям рекомендуется хранить массив объектов QModelRoleData (и, возможно, соответствующий диапазон) и повторно использовать его в последующих вызовах модели. Это позволяет уменьшить выделение памяти, связанное с созданием и возвратом объектов QVariant.

Наконец, с учётом объекта QModelRoleDataSpan, обязанность модели заключается в заполнении данных, соответствующих каждой роли в диапазоне. Способ выполнения зависит от конкретного класса модели. Вот набросок возможной реализации, которая итерирует по диапазону и использует setData() для каждого элемента:

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

См. также Программирование модели/представления и QAbstractItemModel::multiData().

Документация функций-членов

template <typename Container, if_compatible_container<Container>> QModelRoleDataSpan::QModelRoleDataSpan(Container &c)

Создает QModelRoleDataSpan, охватывающий контейнер c, который может быть любым непрерывным контейнером объектов QModelRoleData. Например, это может быть QVector<QModelRoleData>, std::array<QModelRoleData, 10> и т. д.

Примечание: Контейнер должен сохраняться до тех пор, пока этот объект не будет уничтожен.

QModelRoleDataSpan::QModelRoleDataSpan(QModelRoleData *modelRoleData, qsizetype len)

Создаёт QModelRoleDataSpan, охватывающий массив, начинающийся с modelRoleData и имеющий длину len.

Примечание: Массив должен сохраняться до тех пор, пока этот объект не будет уничтожен.

QModelRoleDataSpan::QModelRoleDataSpan(QModelRoleData &modelRoleData)

Создаёт QModelRoleDataSpan, охватывающий modelRoleData, рассматриваемый как массив из 1 элемента.

QModelRoleDataSpan::QModelRoleDataSpan()

Создаёт пустой QModelRoleDataSpan. Его data() будет равен nullptr, а его длина — нулю.

QModelRoleData *QModelRoleDataSpan::begin() const

Возвращает указатель на начало диапазона, представленного этим объектом.

QModelRoleData *QModelRoleDataSpan::data() const

Возвращает указатель на начало диапазона, представленного этим объектом.

QVariant *QModelRoleDataSpan::dataForRole(int role) const

Возвращает данные, связанные с первым QModelRoleData в диапазоне, имеющим роль, равную role. Если такой объект QModelRoleData не существует, поведение не определено.

Примечание: Избегайте вызова этой функции со стороны модели, так как модель не может заранее знать, какие роли находятся в данном QModelRoleDataSpan. Эта функция вместо этого подходит для представлений и делегатов, которые контролируют роли в диапазоне.

См. также QModelRoleData::data().

QModelRoleData *QModelRoleDataSpan::end() const

Возвращает указатель на воображаемый элемент, следующий за концом диапазона, представленного этим объектом.

qsizetype QModelRoleDataSpan::length() const

Возвращает длину диапазона, представленного этим объектом.

qsizetype QModelRoleDataSpan::size() const

Возвращает длину диапазона, представленного этим объектом.

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

Возвращает ссылку на изменяемый QModelRoleData в позиции index в диапазоне.

Примечание: index должен быть допустимым индексом для этого диапазона (0 <= index < size()).