| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example itemviews/customsortfiltermodel |
| \title Custom Sort/Filter Model Example |
| \ingroup examples-itemviews |
| \brief The Custom Sort/Filter Model example illustrates how to subclass |
| QSortFilterProxyModel to perform advanced sorting and filtering. |
| |
| \image customsortfiltermodel-example.png Screenshot of the Custom Sort/Filter Model Example |
| |
| The QSortFilterProxyModel class provides support for sorting and |
| filtering data passed between another model and a view. |
| |
| The model transforms the structure of a source model by mapping |
| the model indexes it supplies to new indexes, corresponding to |
| different locations, for views to use. This approach allows a |
| given source model to be restructured as far as views are |
| concerned, without requiring any transformations on the underlying |
| data and without duplicating the data in memory. |
| |
| The Custom Sort/Filter Model example consists of two classes: |
| |
| \list |
| |
| \li The \c MySortFilterProxyModel class provides a custom proxy |
| model. |
| |
| \li The \c Window class provides the main application window, |
| using the custom proxy model to sort and filter a standard |
| item model. |
| |
| \endlist |
| |
| We will first take a look at the \c MySortFilterProxyModel class |
| to see how the custom proxy model is implemented, then we will |
| take a look at the \c Window class to see how the model is |
| used. Finally we will take a quick look at the \c main() function. |
| |
| \section1 MySortFilterProxyModel Class Definition |
| |
| The \c MySortFilterProxyModel class inherits the |
| QSortFilterProxyModel class. |
| |
| Since QAbstractProxyModel and its subclasses are derived from |
| QAbstractItemModel, much of the same advice about subclassing |
| normal models also applies to proxy models. |
| |
| On the other hand, it is worth noting that many of |
| QSortFilterProxyModel's default implementations of functions are |
| written so that they call the equivalent functions in the relevant |
| source model. This simple proxying mechanism may need to be |
| overridden for source models with more complex behavior. In this |
| example we derive from the QSortFilterProxyModel class to ensure |
| that our filter can recognize a valid range of dates, and to |
| control the sorting behavior. |
| |
| \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.h 0 |
| |
| We want to be able to filter our data by specifying a given period |
| of time. For that reason, we implement the custom \c |
| setFilterMinimumDate() and \c setFilterMaximumDate() functions as |
| well as the corresponding \c filterMinimumDate() and \c |
| filterMaximumDate() functions. We reimplement |
| QSortFilterProxyModel's \l |
| {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} |
| function to only accept rows with valid dates, and |
| QSortFilterProxyModel::lessThan() to be able to sort the senders |
| by their email addresses. Finally, we implement a \c dateInRange() |
| convenience function that we will use to determine if a date is |
| valid. |
| |
| \section1 MySortFilterProxyModel Class Implementation |
| |
| The \c MySortFilterProxyModel constructor is trivial, passing the |
| parent parameter on to the base class constructor: |
| |
| \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 0 |
| |
| The most interesting parts of the \c MySortFilterProxyModel |
| implementation are the reimplementations of |
| QSortFilterProxyModel's \l |
| {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} |
| and \l {QSortFilterProxyModel::lessThan()}{lessThan()} |
| functions. Let's first take a look at our customized \c lessThan() |
| function. |
| |
| \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 4 |
| |
| We want to sort the senders by their email addresses. The \l |
| {QSortFilterProxyModel::}{lessThan()} function is used as the < |
| operator when sorting. The default implementation handles a |
| collection of types including QDateTime and String, but in order |
| to be able to sort the senders by their email addresses we must |
| first identify the address within the given string: |
| |
| \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 6 |
| |
| We use QRegularExpression to define a pattern for the addresses we |
| are looking for. The \l {QRegularExpression::match()}{match()} function |
| returns a QRegularExpressionMatch object which contains the result of |
| the matching. If there is a match, |
| \l {QRegularExpressionMatch::hasMatch()}{hasMatch()} returns true. The |
| result of the match can be retrieved with QRegularExpressionMatch's |
| \l {QRegularExpressionMatch::captured()}{captured()} function. |
| The entire match has index 0 and the parenthesized |
| subexpressions have indexes starting from 1 (excluding |
| non-capturing parentheses). |
| |
| \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 3 |
| |
| The \l |
| {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} |
| function, on the other hand, is expected to return true if the |
| given row should be included in the model. In our example, a row |
| is accepted if either the subject or the sender contains the given |
| regular expression, and the date is valid. |
| |
| \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 7 |
| |
| We use our custom \c dateInRange() function to determine if a date |
| is valid. |
| |
| To be able to filter our data by specifying a given period of |
| time, we also implement functions for getting and setting the |
| minimum and maximum dates: |
| |
| \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 1 |
| \codeline |
| \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 2 |
| |
| The get functions, \c filterMinimumDate() and \c |
| filterMaximumDate(), are trivial and implemented as inline |
| function in the header file. |
| |
| This completes our custom proxy model. Let's see how we can use it |
| in an application. |
| |
| \section1 Window Class Definition |
| |
| The \c CustomFilter class inherits QWidget, and provides this |
| example's main application window: |
| |
| \snippet itemviews/customsortfiltermodel/window.h 0 |
| |
| We implement two private slots, \c textFilterChanged() and \c |
| dateFilterChanged(), to respond to the user changing the filter |
| pattern, case sensitivity, or any of the dates. In addition, we |
| implement a public \c setSourceModel() convenience function to set |
| up the model/ view relation. |
| |
| \section1 Window Class Implementation |
| |
| In this example, we have chosen to create and set the source model |
| in the \c main () function (which we will come back to later). So |
| when constructing the main application window, we assume that a |
| source model already exists and start by creating an instance of |
| our custom proxy model: |
| |
| \snippet itemviews/customsortfiltermodel/window.cpp 0 |
| |
| We set the \l |
| {QSortFilterProxyModel::dynamicSortFilter}{dynamicSortFilter} |
| property that holds whether the proxy model is dynamically sorted |
| and filtered. By setting this property to true, we ensure that the |
| model is sorted and filtered whenever the contents of the source |
| model change. |
| |
| The main application window shows views of both the source model |
| and the proxy model. The source view is quite simple: |
| |
| \snippet itemviews/customsortfiltermodel/window.cpp 1 |
| |
| The QTreeView class provides a default model/view implementation |
| of a tree view. Our view implements a tree representation of items |
| in the application's source model. |
| |
| \snippet itemviews/customsortfiltermodel/window.cpp 2 |
| |
| The QTreeView class provides a default model/view implementation |
| of a tree view; our view implements a tree representation of items |
| in the application's source model. We add our view widget to a |
| layout that we install on a corresponding group box. |
| |
| The proxy model view, on the other hand, contains several widgets |
| controlling the various aspects of transforming the source model's |
| data structure: |
| |
| \snippet itemviews/customsortfiltermodel/window.cpp 3 |
| \snippet itemviews/customsortfiltermodel/window.cpp 4 |
| |
| Note that whenever the user changes one of the filtering options, |
| we must explicitly reapply the filter. This is done by connecting |
| the various editors to functions that update the proxy model. |
| |
| \snippet itemviews/customsortfiltermodel/window.cpp 5 |
| |
| The sorting will be handled by the view. All we have to do is to |
| enable sorting for our proxy view by setting the |
| QTreeView::sortingEnabled property (which is false by |
| default). Then we add all the filtering widgets and the proxy view |
| to a layout that we install on a corresponding group box. |
| |
| \snippet itemviews/customsortfiltermodel/window.cpp 6 |
| |
| Finally, after putting our two group boxes into another layout |
| that we install on our main application widget, we customize the |
| application window. |
| |
| As mentioned above, we create the source model in the \c main () |
| function, calling the \c Window::setSourceModel() function to make |
| the application use it: |
| |
| \snippet itemviews/customsortfiltermodel/window.cpp 7 |
| |
| The QSortFilterProxyModel::setSourceModel() function makes the |
| proxy model process the data in the given model, in this case out |
| mail model. The \l {QAbstractItemView::}{setModel()} that the |
| view widget inherits from the QAbstractItemModel class, sets the |
| model for the view to present. Note that the latter function will |
| also create and set a new selection model. |
| |
| \snippet itemviews/customsortfiltermodel/window.cpp 8 |
| |
| The \c textFilterChanged() function is called whenever the user |
| changes the filter pattern or the case sensitivity. |
| |
| We first retrieve the preferred syntax (the QRegExp::PatternSyntax |
| enum is used to interpret the meaning of the given pattern), then |
| we determine the preferred case sensitivity. Based on these |
| preferences and the current filter pattern, we set the proxy |
| model's \l {QSortFilterProxyModel::}{filterRegExp} property. The |
| \l {QSortFilterProxyModel::}{filterRegExp} property holds the |
| regular expression used to filter the contents of the source |
| model. Note that calling QSortFilterProxyModel's \l |
| {QSortFilterProxyModel::}{setFilterRegExp()} function also updates |
| the model. |
| |
| \snippet itemviews/customsortfiltermodel/window.cpp 9 |
| |
| The \c dateFilterChanged() function is called whenever the user |
| modifies the range of valid dates. We retrieve the new dates from |
| the user interface, and call the corresponding functions (provided |
| by our custom proxy model) to set the proxy model's minimum and |
| maximum dates. As we explained above, calling these functions also |
| updates the model. |
| |
| \section1 The Main() Function |
| |
| In this example, we have separated the application from the source |
| model by creating the model in the \c main () function. First we |
| create the application, then we create the source model: |
| |
| \snippet itemviews/customsortfiltermodel/main.cpp 0 |
| |
| The \c createMailModel() function is a convenience function |
| provided to simplify the constructor. All it does is to create and |
| return a model describing a collection of emails. The model is an |
| instance of the QStandardItemModel class, i.e., a generic model |
| for storing custom data typically used as a repository for |
| standard Qt data types. Each mail description is added to the |
| model using \c addMail(), another convenience function. See \c |
| {itemviews/customsortfiltermodel/main.cpp} for details. |
| */ |
