SortFilterProxyModel QML Type | Qt 6.10
Description: Provides sorting and filtering capabilities for a QAbstractItemModel.

- Qt 6.10
- QML Types
- QtQml.Models
- SortFilterProxyModel
- Qt 6.10.3 Reference Documentation

# SortFilterProxyModel QML Type

Provides sorting and filtering capabilities for a QAbstractItemModel. More...

Import Statement: | `import QtQml.Models`
Since: | Qt 6.10
Status: | Preliminary

This type is under development and is subject to change.

- List of all members, including inherited members

## Properties

- autoAcceptChildRows : bool
- dynamicSortFilter : bool
- filters : list<Filter>
- model : var
- recursiveFiltering : bool
- sorters : list<Sorter>

## Methods

- invalidate()
- invalidateSorter()
- setPrimarySorter(sorter)

## Detailed Description

SortFilterProxyModel inherits from QAbstractProxyModel, which handles the transformation of source indexes into proxy indexes. Sorting and filtering are controlled via the sorters and filters properties, which determine the order of execution as specified in QML. This order can be overridden using the priority property available for each sorter. By default, all sorters share the same priority.

SortFilterProxyModel enables users to sort and filter a QAbstractItemModel. The item views such as TableView or TreeView can utilize this proxy model to display filtered content.

Note: Currently, SortFilterProxyModel supports only QAbstractItemModel as the source model.

The snippet below shows the configuration of sorters and filters in the QML SortFilterProxyModel:

     ProcessModel { id: processModel }

     SortFilterProxyModel {
         id: sfpm
         model: processModel
         sorters: [
             RoleSorter: {
                 roleName: "user"
                 priority: 0
             },
             RoleSorter: {
                 roleName: "pid"
                 priority: 1
             }
         ]
         filters: [
             FunctionFilter: {
                 component RoleData: QtObject { property qreal cpuUsage }
                 function filter(data: RoleData) : bool {
                     return (data.cpuUsage > 90)
                 }
             }
         ]
     }

The SortFilterProxyModel dynamically sorts and filters data whenever there is a change to the data in the source model and can be disabled through the dynamicSortFilter property.

The sorters RoleSorter, StringSorter and FunctionSorter can be configured in SortFilterProxyModel. Each sorter can be configured with a specific column index through column property. If a column index is not specified, the sorting will be applied to the column index 0 of the model by default. The execution order of the sorter can be modified through the priority property. This is particularly useful when performing hierarchical sorting, such as sorting data in the first column and then applying sorting to subsequent columns.

To disable a specific sorter, enabled can be set to `false`.

The sorter priority can also be overridden by setting the primary sorter through the method call setPrimarySorter(). This would be helpful in the case where the view wants to sort the data of any specific column by clicking on the column header such as in TableView, when there are other sorters also configured for the model.

The filter ValueFilter and FunctionFilter can be configured in SortFilterProxyModel. Each filter can be set with the column property, similar to the sorter, to filter data in a specific column. If no column is specified, then the filter will be applied to all the column indexes in the model. To reduce the overhead of unwanted checks during filtering, it's recommended to specify the column index.

To disable a specific filter, enabled can be set to `false`.

     ListModel {
         id: listModel
         ListElement { name: "Adan"; age: 25; department: "Process"; pid: 209711; country: "Norway" }
         ListElement { name: "Hannah"; age: 48; department: "HR"; pid: 154916; country: "Germany" }
         ListElement { name: "Divina"; age: 63; department: "Marketing"; pid: 158038; country: "Spain" }
         ListElement { name: "Rohith"; age: 35; department: "Process"; pid: 202582; country: "India" }
         ListElement { name: "Latesha"; age: 23; department: "Quality"; pid: 232582; country: "UK" }
     }

     SortFilterProxyModel {
         id: ageFilterModel
         model: listModel
         filters: [
             AgeFilter { }
         ]
         sorters: [
             RoleSorter { roleName: "department" }
         ]
     }

     ListView {
         anchors.fill: parent
         clip: true
         model: ageFilterModel
         delegate: Rectangle {
             implicitWidth: 100
             implicitHeight: 50
             border.width: 1
             Text {
                 text: name
                 anchors.centerIn: parent
             }
         }
     }

The AgeFilter in the above code snippet can be declared as follows

     FunctionFilter {
        component RoleData: QtObject { property int age }
        function filter(data: RoleData) : bool {
           return data.age > 30
        }
     }

Note: This API is considered tech preview and may change or be removed in future versions of Qt.

## Property Documentation

autoAcceptChildRows : bool

This property will not filter out children of accepted rows. The behavior is similar to that of autoAcceptChildRows in QSortFilterProxyModel.

The default value is `false`.

dynamicSortFilter : bool

This property holds whether the proxy model is dynamically sorted and filtered whenever the contents of the source model change.

The default value is `true`.

filters : list<Filter>

This property holds the list of filters for the SortFilterProxyModel. If no priority is set, the SortFilterProxyModel applies a filter in the order as specified in the list.

model : var

This property allows to set source model for the sort filter proxy model.

recursiveFiltering : bool

This property allows all the configured filters to be applied recursively on children. The behavior is similar to that of recursiveFilteringEnabled in QSortFilterProxyModel.

The default value is `false`.

sorters : list<Sorter>

This property holds the list of sorters for the SortFilterProxyModel. If no priority is set, the SortFilterProxyModel applies a sorter in the order as specified in the list.

## Method Documentation

invalidate()

This method invalidates the model by reevaluating the configured filters and sorters on the source model data.

invalidateSorter()

This method force the sort filter proxy model to reevaluate the configured sorters against the data. It can used in the case where dynamic sorting was disabled through property dynamicSortFilter

setPrimarySorter(sorter)

This method allows to set the primary sorter in the sort filter proxy model. The primary sorter will be evaluated before all other sorters configured as part of sorter property. If not configured or passed `null`, the sorter with higher priority shall be considered as the primary sorter.