Класс QSortFilterProxyModel

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

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

Свойства

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

Публичные функции

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

• 28 общедоступные функции, унаследованные от QAbstractProxyModel
• 40 общедоступные функции, унаследованные от QAbstractItemModel
• 32 общедоступные функции, унаследованные от QObject

Публичные слоты

• 2 публичных слота, унаследованные от QAbstractItemModel
• 1 публичный слот, унаследованный от QObject

Защищённые функции

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

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

• 1 сигнал, унаследованный от QAbstractProxyModel
• 18 сигналов, унаследованных от QAbstractItemModel
• 2 сигнала, унаследованные от QObject
• 11 статических общедоступных членов, унаследованных от 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.

Пример базовой модели сортировки/фильтрации и Пример пользовательской модели сортировки/фильтрации иллюстрируют, как использовать 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 QRegExp emailPattern("[\\w\\.]*@[\\w\\.]*)");

        QString leftString = leftData.toString();
        if(left.column() == 1 && emailPattern.indexIn(leftString) != -1)
            leftString = emailPattern.cap(1);

        QString rightString = rightData.toString();
        if(right.column() == 1 && emailPattern.indexIn(rightString) != -1)
            rightString = emailPattern.cap(1);

        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);

Для иерархических моделей фильтр применяется рекурсивно ко всем дочерним элементам. Если элемент-родитель не соответствует фильтру, то не будут отображаться ни один из его дочерних элементов.

Распространённым случаем использования является предоставление пользователю возможности указать фильтр regular expression, шаблон подстановки или строку в QLineEdit и подключение сигнала textChanged() к setFilterRegExp(), 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(), вы также должны предоставить её в прокси-модели.

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

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