Класс QSortFilterProxyModel

Класс 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().

Примеры 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 может использоваться для скрытия элементов, которые не соответствуют определенному фильтру. Фильтр задается с помощью объекта QRegularExpression и применяется к filterRole() (по умолчанию Qt::DisplayRole) каждого элемента для заданной колонки. Объект QRegularExpression может использоваться для сопоставления регулярного выражения, шаблона с подстановкой или фиксированной строки. Например:

        proxyModel->setFilterRegularExpression(QRegularExpression("\.png", QRegularExpression::CaseInsensitiveOption));
        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(filterRegularExpression())
            || sourceModel()->data(index1).toString().contains(filterRegularExpression()))
            && dateInRange(sourceModel()->data(index2).toDate());
}

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

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

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

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

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

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

QSortFilterProxyModel::QSortFilterProxyModel(QObject *parent = nullptr)

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

[signal, since 6.0] void QSortFilterProxyModel::autoAcceptChildRowsChanged(bool autoAcceptChildRows)

Этот сигнал излучается при изменении значения свойства autoAcceptChildRows.

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

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

См. также autoAcceptChildRows.

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

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

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

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

[signal, since 5.15] void QSortFilterProxyModel::filterRoleChanged(int filterRole)

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

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

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

[slot] void QSortFilterProxyModel::invalidate()

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

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

[signal, since 5.15] void QSortFilterProxyModel::recursiveFilteringEnabledChanged(bool recursiveFilteringEnabled)

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

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

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

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

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

Этот метод сбросит параметры регулярного выражения, но сохранит чувствительность к регистру.

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

[slot, since 5.12] 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(), setFilterRegularExpression(), setFilterFixedString(), и filterRegularExpression().

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

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

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

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

[signal, since 5.15] void QSortFilterProxyModel::sortLocaleAwareChanged(bool sortLocaleAware)

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

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

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

[signal, since 5.15] 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.

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

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

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

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

См. также filterAcceptsColumn(), setFilterFixedString(), setFilterRegularExpression(), и 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, since 6.0] void QSortFilterProxyModel::invalidateColumnsFilter()

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

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

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

См. также invalidate(), invalidateFilter() и invalidateRowsFilter().

[protected] void QSortFilterProxyModel::invalidateFilter()

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

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

См. также invalidate(), invalidateColumnsFilter() и invalidateRowsFilter().

[protected, since 6.0] void QSortFilterProxyModel::invalidateRowsFilter()

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

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

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

См. также invalidate(), invalidateFilter() и invalidateColumnsFilter().

[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::SortOrder QSortFilterProxyModel::sortOrder() const

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

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

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