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

Примечание: По умолчанию модель динамически пересортировывает и перефильтровывает данные при каждом изменении исходной модели. Это поведение можно изменить, задав свойство 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.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;
    }
}

(Этот фрагмент кода взят из примера Пользовательской сортировки/фильтрации модели.)

Альтернативный подход к сортировке — это отключение сортировки в представлении и навязывание определенного порядка пользователю. Это делается путем явного вызова 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(). Например (из примера Пользовательской сортировки/фильтрации модели), следующая реализация игнорирует свойство 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());
}

(Этот фрагмент кода взят из примера Пользовательской сортировки/фильтрации модели.)

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

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

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

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

См. также QAbstractProxyModel, QAbstractItemModel, Программирование моделей/представлений, Пример базовой сортировки/фильтрации модели, Пример пользовательской сортировки/фильтрации модели и 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.

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

См. также filterAcceptsRow(), setFilterFixedString(), setFilterRegularExpression() и 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(), 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.