diff options
| -rw-r--r-- | src/gui/itemviews/qsortfilterproxymodel.cpp | 171 |
1 files changed, 82 insertions, 89 deletions
diff --git a/src/gui/itemviews/qsortfilterproxymodel.cpp b/src/gui/itemviews/qsortfilterproxymodel.cpp index 8444a5b..aef59b5 100644 --- a/src/gui/itemviews/qsortfilterproxymodel.cpp +++ b/src/gui/itemviews/qsortfilterproxymodel.cpp @@ -1278,82 +1278,76 @@ void QSortFilterProxyModelPrivate::_q_sourceColumnsRemoved( /*! \since 4.1 \class QSortFilterProxyModel - \brief The QSortFilterProxyModel class provides support for sorting and filtering data passed - between another model and a view. + \brief The QSortFilterProxyModel class provides support for sorting and + filtering data passed between another model and a view. \ingroup model-view - QSortFilterProxyModel can be used for sorting items, filtering - out items, or both. 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 + QSortFilterProxyModel can be used for sorting items, filtering out items, + or both. 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. - Let's assume that we want to sort and filter the items provided - by a custom model. The code to set up the model and the view, \e - without sorting and filtering, would look like this: + Let's assume that we want to sort and filter the items provided by a custom + model. The code to set up the model and the view, \e without sorting and + filtering, would look like this: \snippet doc/src/snippets/qsortfilterproxymodel-details/main.cpp 1 - To add sorting and filtering support to \c MyItemModel, we need - to create a QSortFilterProxyModel, call setSourceModel() with the - \c MyItemModel as argument, and install the QSortFilterProxyModel - on the view: + To add sorting and filtering support to \c MyItemModel, we need to create + a QSortFilterProxyModel, call setSourceModel() with the \c MyItemModel as + argument, and install the QSortFilterProxyModel on the view: \snippet doc/src/snippets/qsortfilterproxymodel-details/main.cpp 0 \snippet doc/src/snippets/qsortfilterproxymodel-details/main.cpp 2 - At this point, neither sorting nor filtering is enabled; the - original data is displayed in the view. Any changes made through - the QSortFilterProxyModel are applied to the original model. + At this point, neither sorting nor filtering is enabled; the original data + is displayed in the view. Any changes made through the + QSortFilterProxyModel are applied to the original model. - The QSortFilterProxyModel acts as a wrapper for the original - model. If you need to convert source \l{QModelIndex}es to - sorted/filtered model indexes or vice versa, use mapToSource(), - mapFromSource(), mapSelectionToSource(), and - mapSelectionFromSource(). + The QSortFilterProxyModel acts as a wrapper for the original model. If you + need to convert source \l{QModelIndex}es to sorted/filtered model indexes + or vice versa, use mapToSource(), mapFromSource(), mapSelectionToSource(), + and mapSelectionFromSource(). - \note By default, the model does not dynamically re-sort and re-filter - data whenever the original model changes. This behavior can be - changed by setting the \l{QSortFilterProxyModel::dynamicSortFilter} - {dynamicSortFilter} property. + \note By default, the model does not dynamically re-sort and re-filter data + whenever the original model changes. This behavior can be changed by + setting the \l{QSortFilterProxyModel::dynamicSortFilter}{dynamicSortFilter} + property. - The \l{itemviews/basicsortfiltermodel}{Basic Sort/Filter Model} - and \l{itemviews/customsortfiltermodel}{Custom Sort/Filter Model} - examples illustrate how to use QSortFilterProxyModel to perform - basic sorting and filtering and how to subclass it to implement - custom behavior. + The \l{itemviews/basicsortfiltermodel}{Basic Sort/Filter Model} and + \l{itemviews/customsortfiltermodel}{Custom Sort/Filter Model} examples + illustrate how to use QSortFilterProxyModel to perform basic sorting and + filtering and how to subclass it to implement custom behavior. \section1 Sorting QTableView and QTreeView have a - \l{QTreeView::sortingEnabled}{sortingEnabled} property that - controls whether the user can sort the view by clicking the - view's horizontal header. For example: + \l{QTreeView::sortingEnabled}{sortingEnabled} property that controls + whether the user can sort the view by clicking the view's horizontal + header. For example: \snippet doc/src/snippets/qsortfilterproxymodel-details/main.cpp 3 - When this feature is on (the default is off), clicking on a - header section sorts the items according to that column. By - clicking repeatedly, the user can alternate between ascending and - descending order. + When this feature is on (the default is off), clicking on a header section + sorts the items according to that column. By clicking repeatedly, the user + can alternate between ascending and descending order. \image qsortfilterproxymodel-sorting.png A sorted QTreeView - Behind the scene, the view calls the sort() virtual function on - the model to reorder the data in the model. To make your data - sortable, you can either implement sort() in your model, or you - use a QSortFilterProxyModel to wrap your model -- - QSortFilterProxyModel provides a generic sort() reimplementation - that operates on the sortRole() (Qt::DisplayRole by default) of - the items and that understands several data types, including \c - int, QString, and QDateTime. For hierarchical models, sorting is - applied recursively to all child items. String comparisons are - case sensitive by default; this can be changed by setting the - \l{QSortFilterProxyModel::}{sortCaseSensitivity} property. + Behind the scene, the view calls the sort() virtual function on the model + to reorder the data in the model. To make your data sortable, you can + either implement sort() in your model, or use a QSortFilterProxyModel to + wrap your model -- QSortFilterProxyModel provides a generic sort() + reimplementation that operates on the sortRole() (Qt::DisplayRole by + default) of the items and that understands several data types, including + \c int, QString, and QDateTime. For hierarchical models, sorting is applied + recursively to all child items. String comparisons are case sensitive by + default; this can be changed by setting the \l{QSortFilterProxyModel::} + {sortCaseSensitivity} property. Custom sorting behavior is achieved by subclassing QSortFilterProxyModel and reimplementing lessThan(), which is @@ -1365,43 +1359,42 @@ void QSortFilterProxyModelPrivate::_q_sourceColumnsRemoved( \l{itemviews/customsortfiltermodel}{Custom Sort/Filter Model} example.) - An alternative approach to sorting is to disable sorting on the - view and to impose a certain order to the user. This is done by - explicitly calling sort() with the desired column and order as - arguments on the QSortFilterProxyModel (or on the original model - if it implements sort()). For example: + An alternative approach to sorting is to disable sorting on the view and to + impose a certain order to the user. This is done by explicitly calling + sort() with the desired column and order as arguments on the + QSortFilterProxyModel (or on the original model if it implements sort()). + For example: \snippet doc/src/snippets/qsortfilterproxymodel-details/main.cpp 4 - QSortFilterProxyModel can be sorted by column -1, in which case it - returns to the sort order of the underlying source model. + QSortFilterProxyModel can be sorted by column -1, in which case it returns + to the sort order of the underlying source model. \section1 Filtering - In addition to sorting, QSortFilterProxyModel can be used to hide - items that don't match a certain filter. The filter is specified - using a QRegExp object and is applied to the filterRole() - (Qt::DisplayRole by default) of each item, for a given column. - The QRegExp object can be used to match a regular expression, a - wildcard pattern, or a fixed string. For example: + In addition to sorting, QSortFilterProxyModel can be used to hide items + that do not match a certain filter. The filter is specified using a QRegExp + object and is applied to the filterRole() (Qt::DisplayRole by default) of + each item, for a given column. The QRegExp object can be used to match a + regular expression, a wildcard pattern, or a fixed string. For example: \snippet doc/src/snippets/qsortfilterproxymodel-details/main.cpp 5 - For hierarchical models, the filter is applied recursively to all - children. If a parent item doesn't match the filter, none of its - children will be shown. + For hierarchical models, the filter is applied recursively to all children. + If a parent item doesn't match the filter, none of its children will be + shown. - A common use case is to let the user specify the filter regexp, - wildcard pattern, or fixed string in a QLineEdit and to connect - the \l{QLineEdit::textChanged()}{textChanged()} signal to - setFilterRegExp(), setFilterWildcard(), or setFilterFixedString() - to reapply the filter. + A common use case is to let the user specify the filter regexp, wildcard + pattern, or fixed string in a QLineEdit and to connect the + \l{QLineEdit::textChanged()}{textChanged()} signal to setFilterRegExp(), + setFilterWildcard(), or setFilterFixedString() to reapply the filter. Custom filtering behavior can be achieved by reimplementing the filterAcceptsRow() and filterAcceptsColumn() functions. For - example, the following implementation ignores the - \l{QSortFilterProxyModel::filterKeyColumn}{filterKeyColumn} - property and performs filtering on columns 0, 1, and 2: + example (from the \l{itemviews/customsortfiltermodel} + {Custom Sort/Filter Model} example), the following implementation ignores + the \l{QSortFilterProxyModel::filterKeyColumn}{filterKeyColumn} property + and performs filtering on columns 0, 1, and 2: \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 3 @@ -1411,24 +1404,24 @@ void QSortFilterProxyModelPrivate::_q_sourceColumnsRemoved( If you are working with large amounts of filtering and have to invoke invalidateFilter() repeatedly, using reset() may be more efficient, - depending on the implementation of your model. However, note that reset() - returns the proxy model to its original state, losing selection - information, and will cause the proxy model to be repopulated. + depending on the implementation of your model. However, reset() returns the + proxy model to its original state, losing selection information, and will + cause the proxy model to be repopulated. \section1 Subclassing - \bold{Note:} Some general guidelines for subclassing models are - available in the \l{Model Subclassing Reference}. - Since QAbstractProxyModel and its subclasses are derived from - QAbstractItemModel, much of the same advice about subclassing normal - models also applies to proxy models. In addition, it is worth noting - that many of the default implementations of functions in this class - 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; for example, if the - source model provides a custom hasChildren() implementation, you - should also provide one in the proxy model. + QAbstractItemModel, much of the same advice about subclassing normal models + also applies to proxy models. In addition, it is worth noting that many of + the default implementations of functions in this class 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; for example, if the source model provides a custom + hasChildren() implementation, you should also provide one in the proxy + model. + + \note Some general guidelines for subclassing models are available in the + \l{Model Subclassing Reference}. \sa QAbstractProxyModel, QAbstractItemModel, {Model/View Programming}, {Basic Sort/Filter Model Example}, {Custom Sort/Filter Model Example} |