Класс QSortFilterProxyModel

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

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

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

Свойства

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

Реализованные открытые функции

Public Slots

Protected Functions

Detailed Description

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

        proxyModel->setFilterRegExp(QRegExp(".png", Qt::CaseInsensitive,
                                            QRegExp::FixedString));
        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(filterRegExp())
            || sourceModel()->data(index1).toString().contains(filterRegExp()))
            && dateInRange(sourceModel()->data(index2).toDate());
}

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

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

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

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

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

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

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

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

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

QSortFilterProxyModel::QSortFilterProxyModel(QObject *parent = nullptr)

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

void QSortFilterProxyModel::invalidate()

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

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

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

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 внутри.

Этот метод был добавлен в Qt 5.12.

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

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

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

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

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

[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 если значение соответствующего элемента совпадает с строкой фильтра, строкой с подстановкой или регулярным выражением.

Примечание: По умолчанию используется 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().

[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, связанный с индексами QModelIndex. Это можно изменить, установив свойство 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.