Класс 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.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;
    }
}

(Этот фрагмент кода взят из примера 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.

[slot] void QSortFilterProxyModel::invalidate()

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

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

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

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

Эта функция была добавлена в 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. Вы должны переопределить этот метод, чтобы получить описанное поведение.

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