Doc - some clean ups to QSortFilterProxyModel's documentation

Reviewed-By: TrustMe

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}