Класс QSortFilterProxyModel

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

Этот класс был представлен в Qt 4.1.

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

Свойства

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

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

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

Сигналы

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

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

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.

Примеры Basic Sort/Filter Model и Custom Sort/Filter Model иллюстрируют, как использовать 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.userType() == QMetaType::QDateTime) {
        return leftData.toDateTime() < rightData.toDateTime();
    } else {
        static const QRegularExpression emailPattern("[\\w\\.]*@[\\w\\.]*");

        QString leftString = leftData.toString();
        if (left.column() == 1) {
            const QRegularExpressionMatch match = emailPattern.match(leftString);
            if (match.hasMatch())
                leftString = match.captured(0);
        }
        QString rightString = rightData.toString();
        if (right.column() == 1) {
            const QRegularExpressionMatch match = emailPattern.match(rightString);
            if (match.hasMatch())
                rightString = match.captured(0);
        }

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

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

Распространённый случай использования — предоставление пользователю возможности указать регулярное выражение фильтра, шаблон с подстановкой или фиксированную строку в QLineEdit и подключение сигнала textChanged() к setFilterRegularExpression(), 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(), использование beginResetModel() / endResetModel() может быть более эффективным в зависимости от реализации вашей модели. Однако beginResetModel() / endResetModel() возвращает прокси-модель в исходное состояние, теряя информацию о выделении, и заставит прокси-модель быть повторно заполненной.

Наследование

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

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

Примечание: В Qt 5 поддержка регулярных выражений была улучшена с помощью класса QRegularExpression. QSortFilterProxyModel, датируемые периодом до создания этого класса, изначально поддерживали только QRegExp. С Qt 5.12 были добавлены API QRegularExpression. Поэтому API QRegExp следует считать устаревшими, и следует использовать версию QRegularExpression.

Предупреждение: Не смешивайте вызовы методов-геттеров и -сеттеров разных типов регулярных выражений, так как это приведёт к неожиданным результатам. Для максимальной совместимости сохранена исходная реализация. Поэтому, если, например, вызов setFilterRegularExpression выполняется, за которым следует вызов setFilterFixedString, первый вызов настроит объект QRegularExpression для использования в качестве фильтра, в то время как второй — настроит QRegExp в режиме FixedString. Однако это реализационный деталь, который может измениться в будущем.

См. также QAbstractProxyModel, QAbstractItemModel, Программирование с моделями и представлениями, Пример Basic Sort/Filter Model, Пример Custom Sort/Filter Model и QIdentityProxyModel.

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

QSortFilterProxyModel::QSortFilterProxyModel(QObject *parent = nullptr)

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

[signal] void QSortFilterProxyModel::filterCaseSensitivityChanged(Qt::CaseSensitivity filterCaseSensitivity)

Этот сигнал испускается, когда чувствительность к регистру фильтра изменяется на filterCaseSensitivity.

Примечание: Сигнал уведомления для свойства filterCaseSensitivity.

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

[signal] void QSortFilterProxyModel::filterRoleChanged(int filterRole)

Этот сигнал испускается, когда роль фильтра изменяется на filterRole.

Примечание: Сигнал уведомления для свойства filterRole.

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

[slot] void QSortFilterProxyModel::invalidate()

Делает недействительной текущую сортировку и фильтрацию.

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

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

[signal] void QSortFilterProxyModel::recursiveFilteringEnabledChanged(bool recursiveFilteringEnabled)

Этот сигнал испускается, когда настройка рекурсивного фильтра изменяется на recursiveFilteringEnabled.

Примечание: Сигнал уведомления для свойства recursiveFilteringEnabled.

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

[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::setFilterRegularExpression(const QString &pattern)

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

Этот метод следует использовать в новом коде, так как он будет использовать QRegularExpression внутри.

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

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

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

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

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

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

[signal] void QSortFilterProxyModel::sortCaseSensitivityChanged(Qt::CaseSensitivity sortCaseSensitivity)

Этот сигнал испускается, когда чувствительность к регистру при сортировке изменяется на sortCaseSensitivity.

Примечание: Сигнал уведомления для свойства sortCaseSensitivity.

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

[signal] void QSortFilterProxyModel::sortLocaleAwareChanged(bool sortLocaleAware)

Этот сигнал испускается, когда настройка с учётом локали изменяется на sortLocaleAware.

Примечание: Сигнал уведомления для свойства isSortLocaleAware.

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

[signal] void QSortFilterProxyModel::sortRoleChanged(int sortRole)

Этот сигнал испускается, когда роль сортировки изменяется на sortRole.

Примечание: Сигнал уведомления для свойства sortRole.

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

[virtual] QSortFilterProxyModel::~QSortFilterProxyModel()

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

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

Переопределяет: QAbstractProxyModel::buddy(const QModelIndex &index) const.

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

Переопределяет: QAbstractProxyModel::canFetchMore(const QModelIndex &parent) const.

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

Переопределяет: QAbstractItemModel::columnCount(const QModelIndex &parent) const.

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

Переопределяет: QAbstractProxyModel::data(const QModelIndex &proxyIndex, int role) const.

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

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

Переопределяет: QAbstractProxyModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent).

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

Переопределяет: QAbstractProxyModel::fetchMore(const QModelIndex &parent).

[virtual protected] bool QSortFilterProxyModel::filterAcceptsColumn(int source_column, const QModelIndex &source_parent) const

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

Примечание: По умолчанию реализация всегда возвращает true. Вы должны переопределить этот метод, чтобы получить описанное поведение.

См. также 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().

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

Переопределяет: QAbstractProxyModel::flags(const QModelIndex &index) const.

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

Переопределяет: QAbstractProxyModel::hasChildren(const QModelIndex &parent) const.

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

Переопределяет: QAbstractProxyModel::headerData(int section, Qt::Orientation orientation, int role) const.

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

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

Переопределяет: QAbstractItemModel::index(int row, int column, const QModelIndex &parent) const.

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

Переопределяет: QAbstractItemModel::insertColumns(int column, int count, const QModelIndex &parent).

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

Переопределяет: QAbstractItemModel::insertRows(int row, int count, const QModelIndex &parent).

[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.

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

Переопределяет: QAbstractProxyModel::mapFromSource(const QModelIndex &sourceIndex) const.

Возвращает индекс модели QSortFilterProxyModel на основе sourceIndex из модели-источника.

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

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

Переопределяет: QAbstractProxyModel::mapSelectionFromSource(const QItemSelection &sourceSelection) const.

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

Переопределяет: QAbstractProxyModel::mapSelectionToSource(const QItemSelection &proxySelection) const.

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

Переопределяет: QAbstractProxyModel::mapToSource(const QModelIndex &proxyIndex) const.

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

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

[override 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(const QModelIndex &start, int role, const QVariant &value, int hits, Qt::MatchFlags flags) const.

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

Переопределяет: QAbstractProxyModel::mimeData(const QModelIndexList &indexes) const.

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

Переопределяет: QAbstractProxyModel::mimeTypes() const.

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

Переопределяет: QAbstractItemModel::parent(const QModelIndex &index) const.

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

Переопределяет: QAbstractItemModel::removeColumns(int column, int count, const QModelIndex &parent).

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

Переопределяет: QAbstractItemModel::removeRows(int row, int count, const QModelIndex &parent).

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

Переопределяет: QAbstractItemModel::rowCount(const QModelIndex &parent) const.

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

Переопределяет: QAbstractProxyModel::setData(const QModelIndex &index, const QVariant &value, int role).

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

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

Переопределяет: QAbstractProxyModel::setHeaderData(int section, Qt::Orientation orientation, const QVariant &value, int role).

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

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

Переопределяет: QAbstractProxyModel::setSourceModel(QAbstractItemModel *sourceModel).

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

Переопределяет: QAbstractProxyModel::sibling(int row, int column, const QModelIndex &idx) const.

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

Переопределяет: QAbstractProxyModel::sort(int column, Qt::SortOrder order).

int QSortFilterProxyModel::sortColumn() const

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

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

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

Qt::SortOrder QSortFilterProxyModel::sortOrder() const

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

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

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

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

Переопределяет: QAbstractProxyModel::span(const QModelIndex &index) const.

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

Переопределяет: QAbstractProxyModel::supportedDropActions() const.