1  SortFilterProxyModel
  2  ====================
  3  
  4  SortFilterProxyModel is an implementation of `QSortFilterProxyModel` conveniently exposed for QML.
  5  
  6  This is a fork that combines the Qt6 support of
  7  [MenloSystems/SortFilterProxyModel](https://github.com/MenloSystems/SortFilterProxyModel) and
  8  [RaymiiOrg/SortFilterProxyModel](https://github.com/RaymiiOrg/SortFilterProxyModel)
  9  with a custom fixes and improvements. The library is intended to work on both Qt 5 and 6.
 10  
 11  Install
 12  -------
 13  ##### With [qpm](https://qpm.io) :
 14  1. `qpm install fr.grecko.sortfilterproxymodel`
 15  2. add `include(vendor/vendor.pri)` in your .pro if it is not already done
 16  3. `import SortFilterProxyModel 0.2` to use this library in your QML files
 17  
 18  ##### Without qpm :
 19  1. clone or download this repository
 20  2. * `qmake` add `include  (<path/to/SortFilterProxyModel>/SortFilterProxyModel.pri)` in your `.pro`
 21     * `CMake` add $<TARGET_OBJECTS:SortFilterProxyModel> to the sources of your executable target in your cmake project
 22  3. `import SortFilterProxyModel 0.2` to use this library in your QML files
 23  
 24  Sample Usage
 25  ------------
 26  
 27  - You can do simple filtering and sorting with SortFilterProxyModel:
 28  ```qml
 29  import QtQuick 2.2
 30  import QtQuick.Controls 1.2
 31  import SortFilterProxyModel 0.2
 32  
 33  ApplicationWindow {
 34      visible: true
 35      width: 640
 36      height: 480
 37  
 38      ListModel {
 39          id: personModel
 40          ListElement {
 41              firstName: "Erwan"
 42              lastName: "Castex"
 43              favorite: true
 44          }
 45          // ...
 46      }
 47  
 48      TextField {
 49          id: textField
 50          anchors { top: parent.top; left: parent.left; right: parent.right }
 51          height: implicitHeight
 52      }
 53  
 54      SortFilterProxyModel {
 55          id: personProxyModel
 56          sourceModel: personModel
 57          filters: RegExpFilter {
 58              roleName: "lastName"
 59              pattern: textField.text
 60              caseSensitivity: Qt.CaseInsensitive
 61          }
 62          sorters: StringSorter { roleName: "firstName" }
 63      }
 64  
 65      ListView {
 66          anchors { top: textField.bottom; bottom: parent.bottom; left: parent.left; right: parent.right }
 67          model: personProxyModel
 68          delegate: Text { text: model.firstName + " " + model.lastName}
 69      }
 70  }
 71  ```
 72  Here the `ListView` will only show elements that contains the content of the `TextField` in their `lastName` role.
 73  
 74  - But you can also achieve more complex filtering or sorting with multiple `filters` and `sorters`:
 75  ```qml
 76      SortFilterProxyModel {
 77          id: personProxyModel
 78          sourceModel: personModel
 79          filters: [
 80              ValueFilter {
 81                  enabled: onlyShowFavoritesCheckbox.checked
 82                  roleName: "favorite"
 83                  value: true
 84              },
 85              AnyOf {
 86                  RegExpFilter {
 87                      roleName: "lastName"
 88                      pattern: textField.text
 89                      caseSensitivity: Qt.CaseInsensitive
 90                  }
 91                  RegExpFilter {
 92                      roleName: "firstName"
 93                      pattern: textField.text
 94                      caseSensitivity: Qt.CaseInsensitive
 95                  }
 96              }
 97          ]
 98          sorters: [
 99              RoleSorter { roleName: "favorite"; sortOrder: Qt.DescendingOrder },
100              StringSorter { roleName: "firstName" },
101              StringSorter { roleName: "lastName" }
102          ]
103      }
104  
105      CheckBox {
106          id:onlyShowFavoritesCheckbox
107      }
108  ```
109  This will show in the corresponding `ListView` only the elements where the `firstName` or the `lastName` match the text entered in the `textField`, and if the `onlyShowFavoritesCheckbox` is checked it will aditionnally filter the elements where `favorite` is `true`.
110  The favorited elements will be shown first and all the elements are sorted by `firstName` and then `lastName`.
111  
112  Showcase Application
113  --------------------
114  You can find an application showcasing this library here: https://github.com/oKcerG/SFPMShowcase
115  
116  License
117  -------
118  This library is licensed under the MIT License.
119  
120  Documentation
121  -------------
122  This component is a subclass of [`QSortFilterProxyModel`](http://doc.qt.io/qt-5/qsortfilterproxymodel.html), to use it, you need to set the `sourceModel` property to a [`QAbstractItemModel*`](http://doc.qt.io/qt-5/qabstractitemmodel.html) with correct role names.
123  This means you can use it with custom c++ models or `ListModel`, but not with JavaScript models like arrays, integers or object instances.
124  
125  The complete documentation reference is available here: https://okcerg.github.io/SortFilterProxyModel/
126  
127  Contributing
128  ------------
129  Don't hesitate to open an issue about a suggestion, a bug, a lack of clarity in the documentation, etc.
130  
131  Pull requests are also welcome, if it's a important change you should open an issue first though.