Класс QSortFilterProxyModel

Класс QSortFilterProxyModel обеспечивает поддержку сортировки и фильтрации данных, передаваемых между другим моделью и представлением. Подробнее...

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

Свойства

• 1 свойство унаследовано от QAbstractProxyModel
• 1 свойство унаследовано от QObject

Публичные функции

Переопределённые публичные функции

• 28 общедоступных функций унаследовано от QAbstractProxyModel
• 39 общедоступных функций унаследовано от QAbstractItemModel
• 31 общедоступных функций унаследовано от QObject

Публичные слоты

• 2 публичных слота унаследовано от QAbstractItemModel
• 1 публичный слот унаследовано от QObject

Защищенные функции

• 19 защищенных функций унаследовано от QAbstractItemModel
• 9 защищенных функций унаследовано от QObject

Дополнительные унаследованные члены

• 1 сигнал унаследован от QAbstractProxyModel
• 18 сигналов унаследовано от QAbstractItemModel
• 2 сигнала унаследовано от QObject
• 11 статических общедоступных членов унаследовано от QObject
• 1 защищенный слот унаследован от QAbstractProxyModel
• 1 защищенный слот унаследован от QAbstractItemModel

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

Класс QSortFilterProxyModel предоставляет поддержку сортировки и фильтрации данных, передаваемых между другим моделью и представлением.

QSortFilterProxyModel может использоваться для сортировки элементов, фильтрации элементов или для обоих действий. Модель преобразует структуру источника модели, сопоставляя индексы модели, которые она предоставляет, с новыми индексами, соответствующими различным расположениям, для использования представлениями. Этот подход позволяет перестраивать заданную модель источника, что касается представлений, без необходимости каких-либо преобразований в исходных данных и без дублирования данных в памяти.

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

        QTreeView *treeView = new QTreeView;
        MyItemModel *model = new MyItemModel(this);

        treeView->setModel(model);

Чтобы добавить поддержку сортировки и фильтрации к MyItemModel, необходимо создать QSortFilterProxyModel, вызвать setSourceModel() с MyItemModel в качестве аргумента и установить QSortFilterProxyModel в представлении:

        QTreeView *treeView = new QTreeView;
        MyItemModel *sourceModel = new MyItemModel(this);
        QSortFilterProxyModel *proxyModel = new QSortFilterProxyModel(this);

        proxyModel->setSourceModel(sourceModel);
        treeView->setModel(proxyModel);

В этот момент ни сортировка, ни фильтрация не включены; исходные данные отображаются в представлении. Любые изменения, внесённые через QSortFilterProxyModel, применяются к исходной модели.

QSortFilterProxyModel действует как оболочка для исходной модели. Если вам необходимо преобразовать исходные QModelIndex в отсортированные/отфильтрованные индексы модели или наоборот, используйте mapToSource(), mapFromSource(), mapSelectionToSource() и mapSelectionFromSource().

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

Пример базовой сортировки/фильтрации модели и Пример пользовательской сортировки/фильтрации модели иллюстрируют, как использовать QSortFilterProxyModel для выполнения базовой сортировки и фильтрации, а также как подклассировать её для реализации пользовательского поведения.

Сортировка

QTableView и QTreeView имеют свойство sortingEnabled, которое управляет возможностью пользователя сортировать представление, щелкая заголовок представления по горизонтали. Например:

        treeView->setSortingEnabled(true);

Когда эта функция включена (по умолчанию выключена), щелчок по секции заголовка сортирует элементы в соответствии с этим столбцом. Повторным щелчком пользователь может переключаться между возрастанием и убыванием.

За кулисами представление вызывает виртуальную функцию sort() модели, чтобы переупорядочить данные в модели. Чтобы сделать ваши данные сортируемыми, вы можете либо реализовать sort() в своей модели, либо использовать QSortFilterProxyModel для обертывания вашей модели — QSortFilterProxyModel предоставляет общую пере реализацию sort(), которая работает с sortRole() (Qt::DisplayRole по умолчанию) элементов и понимает несколько типов данных, включая int, QString и QDateTime. Для иерархических моделей сортировка применяется рекурсивно ко всем дочерним элементам. Сравнение строк по умолчанию чувствительно к регистру; это можно изменить, установив свойство sortCaseSensitivity.

Пользовательское поведение сортировки достигается путём подклассирования QSortFilterProxyModel и переопределения lessThan(), которое используется для сравнения элементов. Например:

bool MySortFilterProxyModel::lessThan(const QModelIndex &left,
                                      const QModelIndex &right) const
{
    QVariant leftData = sourceModel()->data(left);
    QVariant rightData = sourceModel()->data(right);

    if (leftData.type() == QVariant::DateTime) {
        return leftData.toDateTime() < rightData.toDateTime();
    } else {
        static QRegExp emailPattern("[\\w\\.]*@[\\w\\.]*)");

        QString leftString = leftData.toString();
        if(left.column() == 1 && emailPattern.indexIn(leftString) != -1)
            leftString = emailPattern.cap(1);

        QString rightString = rightData.toString();
        if(right.column() == 1 && emailPattern.indexIn(rightString) != -1)
            rightString = emailPattern.cap(1);

        return QString::localeAwareCompare(leftString, rightString) < 0;
    }
}

(Этот фрагмент кода взят из примера Custom Sort/Filter Model.)

Альтернативный подход к сортировке заключается в отключении сортировки в представлении и навязывании определённого порядка пользователю. Это делается путём явного вызова sort() с желаемым столбцом и порядком в качестве аргументов для QSortFilterProxyModel (или исходной модели, если она реализует sort()). Например:

        proxyModel->sort(2, Qt::AscendingOrder);

QSortFilterProxyModel может быть отсортирован по столбцу -1, в этом случае он возвращается к порядку сортировки основной исходной модели.

Фильтрация

Помимо сортировки, QSortFilterProxyModel может использоваться для скрытия элементов, которые не соответствуют определённому фильтру. Фильтр задаётся с помощью объекта QRegExp и применяется к filterRole() (Qt::DisplayRole по умолчанию) каждого элемента для данного столбца. Объект QRegExp может использоваться для сопоставления регулярного выражения, шаблона подстановочных знаков или фиксированной строки. Например:

        proxyModel->setFilterRegExp(QRegExp(".png", Qt::CaseInsensitive,
                                            QRegExp::FixedString));
        proxyModel->setFilterKeyColumn(1);

Для иерархических моделей фильтр применяется рекурсивно ко всем дочерним элементам. Если родительский элемент не соответствует фильтру, ни один из его дочерних элементов не будет отображаться.

Распространённым случаем использования является предоставление пользователю возможности задавать фильтр regexp, шаблон подстановочных знаков или фиксированную строку в QLineEdit и подключение сигнала textChanged() к setFilterRegExp(), setFilterWildcard() или setFilterFixedString() для повторного применения фильтра.

Пользовательское поведение фильтрации можно достичь, переопределив функции filterAcceptsRow() и filterAcceptsColumn(). Например (из примера Custom Sort/Filter Model), следующая реализация игнорирует свойство filterKeyColumn и выполняет фильтрацию по столбцам 0, 1 и 2:

bool MySortFilterProxyModel::filterAcceptsRow(int sourceRow,
        const QModelIndex &sourceParent) const
{
    QModelIndex index0 = sourceModel()->index(sourceRow, 0, sourceParent);
    QModelIndex index1 = sourceModel()->index(sourceRow, 1, sourceParent);
    QModelIndex index2 = sourceModel()->index(sourceRow, 2, sourceParent);

    return (sourceModel()->data(index0).toString().contains(filterRegExp())
            || sourceModel()->data(index1).toString().contains(filterRegExp()))
            && dateInRange(sourceModel()->data(index2).toDate());
}

(Этот фрагмент кода взят из примера Custom Sort/Filter Model.)

Если вы работаете с большими объёмами фильтрации и вам нужно неоднократно вызывать invalidateFilter(), использование reset() может быть более эффективным, в зависимости от реализации вашей модели. Однако reset() возвращает прокси-модель в её исходное состояние, теряя информацию о выборе, и заставит прокси-модель быть повторно заполненной.

Подклассирование

Поскольку QAbstractProxyModel и её подклассы происходят от QAbstractItemModel, большая часть тех же советов по подклассированию обычных моделей также применима к прокси-моделям. Кроме того, стоит отметить, что многие из реализаций функций в этом классе написаны так, чтобы они вызывали эквивалентные функции в соответствующей исходной модели. Этот простой механизм проксирования может потребовать переопределения для исходных моделей с более сложным поведением; например, если исходная модель предоставляет пользовательскую реализацию hasChildren(), вы также должны предоставить её в прокси-модели.

Примечание: Некоторые общие рекомендации по подклассированию моделей приведены в Справочнике по подклассированию моделей.

См. также QAbstractProxyModel, QAbstractItemModel, Программирование моделей/представлений, Пример базовой сортировки/фильтрации модели, Пример пользовательской сортировки/фильтрации модели и QIdentityProxyModel.

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

QSortFilterProxyModel::QSortFilterProxyModel(QObject *parent = Q_NULLPTR)

Конструирует модель сортировки и фильтрации с заданным parent.

QSortFilterProxyModel::~QSortFilterProxyModel()

Удаляет эту модель сортировки и фильтрации.

QModelIndex QSortFilterProxyModel::buddy(const QModelIndex &index) const

Переопределено из QAbstractItemModel::buddy().

bool QSortFilterProxyModel::canFetchMore(const QModelIndex &parent) const

Переопределено из QAbstractItemModel::canFetchMore().

int QSortFilterProxyModel::columnCount(const QModelIndex &parent = QModelIndex()) const

Переопределено из QAbstractItemModel::columnCount().

QVariant QSortFilterProxyModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const

Переопределено из QAbstractItemModel::data().

См. также setData().

bool QSortFilterProxyModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)

Переопределено из QAbstractItemModel::dropMimeData().

void QSortFilterProxyModel::fetchMore(const QModelIndex &parent)

Переопределено из QAbstractItemModel::fetchMore().

bool QSortFilterProxyModel::filterAcceptsColumn(int source_column, const QModelIndex &source_parent) const

Возвращает значение true если элемент в столбце, указанном с помощью source_column и source_parent, должен быть включён в модель; в противном случае возвращает false.

Реализация по умолчанию возвращает значение true если значение соответствующего элемента совпадает с фильтром, маской или регулярным выражением.

Примечание: По умолчанию, для определения, следует ли принимать столбец или нет, используется Qt::DisplayRole. Это можно изменить, установив свойство filterRole.

См. также filterAcceptsRow(), setFilterFixedString(), setFilterRegExp() и setFilterWildcard().

[virtual protected] bool QSortFilterProxyModel::filterAcceptsRow(int source_row, const QModelIndex &source_parent) const

Возвращает true, если элемент в строке, указанной с помощью source_row и source_parent, должен быть включён в модель; в противном случае возвращает false.

Реализация по умолчанию возвращает true, если значение соответствующего элемента соответствует строке фильтра, строке шаблона или регулярному выражению.

Примечание: По умолчанию, для определения, следует ли принимать строку или нет, используется Qt::DisplayRole. Это можно изменить, установив свойство filterRole.

См. также filterAcceptsColumn(), setFilterFixedString(), setFilterRegExp() и setFilterWildcard().

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

Переопределено из QAbstractItemModel::flags().

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

Переопределено из QAbstractItemModel::hasChildren().

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

Переопределено из QAbstractItemModel::headerData().

См. также setHeaderData().

[virtual] QModelIndex QSortFilterProxyModel::index(int row, int column, const QModelIndex &parent = QModelIndex()) const

Переопределено из QAbstractItemModel::index().

[virtual] bool QSortFilterProxyModel::insertColumns(int column, int count, const QModelIndex &parent = QModelIndex())

Переопределено из QAbstractItemModel::insertColumns().

[virtual] bool QSortFilterProxyModel::insertRows(int row, int count, const QModelIndex &parent = QModelIndex())

Переопределено из QAbstractItemModel::insertRows().

[slot] void QSortFilterProxyModel::invalidate()

Отменяет текущую сортировку и фильтрацию.

Эта функция была добавлена в Qt 4.3.

См. также invalidateFilter().

[protected] void QSortFilterProxyModel::invalidateFilter()

Отменяет текущую фильтрацию.

Эта функция должна вызываться, если вы реализуете пользовательскую фильтрацию (например, filterAcceptsRow()), и параметры фильтра изменились.

Эта функция была добавлена в Qt 4.3.

См. также invalidate().

[virtual protected] bool QSortFilterProxyModel::lessThan(const QModelIndex &source_left, const QModelIndex &source_right) const

Возвращает true, если значение элемента, на который указывает данный индекс source_left, меньше значения элемента, на который указывает данный индекс source_right; в противном случае возвращает false.

Эта функция используется в качестве оператора < при сортировке и обрабатывает следующие типы QVariant:

• QMetaType::Int
• QMetaType::UInt
• QMetaType::LongLong
• QMetaType::ULongLong
• QMetaType::Float
• QMetaType::Double
• QMetaType::QChar
• QMetaType::QDate
• QMetaType::QTime
• QMetaType::QDateTime
• QMetaType::QString

Любой другой тип будет преобразован в QString с помощью QVariant::toString().

Сравнение строк QString по умолчанию чувствительно к регистру; это можно изменить, используя свойство sortCaseSensitivity.

По умолчанию используется Qt::DisplayRole, связанный с QModelIndexes, для сравнений. Это можно изменить, установив свойство sortRole.

Примечание: Передаваемые индексы соответствуют модели-источнику.

См. также sortRole, sortCaseSensitivity и dynamicSortFilter.

[virtual] QModelIndex QSortFilterProxyModel::mapFromSource(const QModelIndex &sourceIndex) const

Переопределено из QAbstractProxyModel::mapFromSource().

Возвращает индекс модели в QSortFilterProxyModel, заданный с помощью sourceIndex из модели-источника.

См. также mapToSource().

[virtual] QItemSelection QSortFilterProxyModel::mapSelectionFromSource(const QItemSelection &sourceSelection) const

Переопределено из QAbstractProxyModel::mapSelectionFromSource().

[virtual] QItemSelection QSortFilterProxyModel::mapSelectionToSource(const QItemSelection &proxySelection) const

Переопределено из QAbstractProxyModel::mapSelectionToSource().

[virtual] QModelIndex QSortFilterProxyModel::mapToSource(const QModelIndex &proxyIndex) const

Переопределено из QAbstractProxyModel::mapToSource().

Возвращает индекс модели-источника, соответствующий заданному proxyIndex из модели сортировки и фильтрации.

См. также mapFromSource().

[virtual] QModelIndexList QSortFilterProxyModel::match(const QModelIndex &start, int role, const QVariant &value, int hits = 1, Qt::MatchFlags flags = Qt::MatchFlags( Qt::MatchStartsWith | Qt::MatchWrap )) const

Переопределено из QAbstractItemModel::match().

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

Переопределено из QAbstractItemModel::mimeData().

[virtual] QStringList QSortFilterProxyModel::mimeTypes() const

Переопределено из QAbstractItemModel::mimeTypes().

[virtual] QModelIndex QSortFilterProxyModel::parent(const QModelIndex &child) const

Переопределено из QAbstractItemModel::parent().

[virtual] bool QSortFilterProxyModel::removeColumns(int column, int count, const QModelIndex &parent = QModelIndex())

Переопределено из QAbstractItemModel::removeColumns().

[virtual] bool QSortFilterProxyModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex())

Переопределено из QAbstractItemModel::removeRows().

[virtual] int QSortFilterProxyModel::rowCount(const QModelIndex &parent = QModelIndex()) const

Переопределено из QAbstractItemModel::rowCount().

[virtual] bool QSortFilterProxyModel::setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)

Переопределено из QAbstractItemModel::setData().

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

[slot] void QSortFilterProxyModel::setFilterFixedString(const QString &pattern)

Устанавливает строку поиска для фильтрации содержимого исходной модели заданным значением pattern.

См. также setFilterCaseSensitivity(), setFilterRegExp(), setFilterWildcard(), и filterRegExp().

[slot] void QSortFilterProxyModel::setFilterRegExp(const QString &pattern)

Это перегруженная функция.

Устанавливает регулярное выражение для фильтрации содержимого исходной модели на pattern.

Примечание: Функция-сеттер для свойства filterRegExp.

См. также setFilterCaseSensitivity(), setFilterWildcard(), setFilterFixedString(), и filterRegExp().

[slot] void QSortFilterProxyModel::setFilterWildcard(const QString &pattern)

Устанавливает выражение с подстановкой для фильтрации содержимого исходной модели заданным значением pattern.

См. также setFilterCaseSensitivity(), setFilterRegExp(), setFilterFixedString(), и filterRegExp().

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

Переопределено из QAbstractItemModel::setHeaderData().

См. также headerData().

[virtual] void QSortFilterProxyModel::setSourceModel(QAbstractItemModel *sourceModel)

Переопределено из QAbstractProxyModel::setSourceModel().

[virtual] QModelIndex QSortFilterProxyModel::sibling(int row, int column, const QModelIndex &idx) const

Переопределено из QAbstractItemModel::sibling().

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

Переопределено из QAbstractItemModel::sort().

int QSortFilterProxyModel::sortColumn() const

Столбец, используемый для сортировки

Возвращает последний использованный столбец сортировки.

Функция была добавлена в Qt 4.5.

Qt::SortOrder QSortFilterProxyModel::sortOrder() const

Порядок, используемый для сортировки

Возвращает последний использованный порядок сортировки.

Функция была добавлена в Qt 4.5.

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

Переопределено из QAbstractItemModel::span().

[virtual] Qt::DropActions QSortFilterProxyModel::supportedDropActions() const

Переопределено из QAbstractItemModel::supportedDropActions().