Класс QSortFilterProxyModel

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

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

Свойства

• 1 свойство унаследовано от QAbstractProxyModel
• 1 свойство унаследовано от QObject

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

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

• 28 public functions inherited from QAbstractProxyModel
• 40 public functions inherited from QAbstractItemModel
• 32 public functions inherited from QObject

Public Slots

• 2 public slots inherited from QAbstractItemModel
• 1 public slot inherited from QObject

Static Public Members

• 10 static public members inherited from QObject

Protected Functions

• 19 защищённых функций унаследовано от QAbstractItemModel
• 9 защищённых функций унаследовано от QObject

Дополнительные унаследованные члены

• 1 сигнал унаследован от QAbstractProxyModel
• 18 сигналов унаследовано от QAbstractItemModel
• 2 сигнала унаследовано от QObject
• 1 защищённый слот унаследован от QAbstractProxyModel
• 1 защищённый слот унаследован от QAbstractItemModel

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

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

Примеры 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(), использование 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, Моделирование/Программирование представлений, Пример Basic Sort/Filter Model, Пример Custom Sort/Filter Model и QIdentityProxyModel.

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

QSortFilterProxyModel::QSortFilterProxyModel(QObject *parent = nullptr)

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

[virtual] QSortFilterProxyModel::~QSortFilterProxyModel()

Уничтожает модель сортировки и фильтрации.

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

Переопределяет метод QAbstractProxyModel::buddy().

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

Переопределено из QAbstractProxyModel::canFetchMore().

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

Переопределено из QAbstractItemModel::columnCount().

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

Переопределено из QAbstractProxyModel::data().

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

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

Переопределено из QAbstractProxyModel::dropMimeData().

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

Переопределено из QAbstractProxyModel::fetchMore().

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

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

Переопределено из QAbstractProxyModel::hasChildren().

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

Переопределено из QAbstractProxyModel::headerData().

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

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

Переопределено из QAbstractItemModel::index().

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

Переопределено из QAbstractItemModel::insertColumns().

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

Переопределено из QAbstractItemModel::insertRows().

[slot] void QSortFilterProxyModel::invalidate()

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

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

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

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

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

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

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

Переопределено из QAbstractProxyModel::mapSelectionFromSource().

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

Переопределено из QAbstractProxyModel::mapSelectionToSource().

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

Переопределено из QAbstractProxyModel::mapToSource().

Возвращает индекс модели-источника, соответствующий данному 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().

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

Переопределено из QAbstractProxyModel::mimeData().

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

Переопределено из QAbstractProxyModel::mimeTypes().

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

Переопределено из QAbstractItemModel::parent().

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

Переопределено из QAbstractItemModel::removeColumns().

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

Переопределено из QAbstractItemModel::removeRows().

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

Переопределено из QAbstractItemModel::rowCount().

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

Переопределено из QAbstractProxyModel::setData().

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

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

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

Переопределено из QAbstractProxyModel::setHeaderData().

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

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

Переопределено из QAbstractProxyModel::setSourceModel().

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

Переопределено из QAbstractProxyModel::sibling().

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

Переопределено из QAbstractProxyModel::sort().

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().

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

Переопределено из QAbstractProxyModel::supportedDropActions().