KItemViews

kcategorizedsortfilterproxymodel.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2007 Rafael Fernández López <[email protected]>
4  SPDX-FileCopyrightText: 2007 John Tapsell <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef KCATEGORIZEDSORTFILTERPROXYMODEL_H
10 #define KCATEGORIZEDSORTFILTERPROXYMODEL_H
11 
12 #include <QSortFilterProxyModel>
13 #include <memory>
14 
15 #include <kitemviews_export.h>
16 class KCategorizedSortFilterProxyModelPrivate;
17 
18 class QItemSelection;
19 
20 /**
21  * @class KCategorizedSortFilterProxyModel kcategorizedsortfilterproxymodel.h KCategorizedSortFilterProxyModel
22  *
23  * This class lets you categorize a view. It is meant to be used along with
24  * KCategorizedView class.
25  *
26  * In general terms all you need to do is to reimplement subSortLessThan() and
27  * compareCategories() methods. In order to make categorization work, you need
28  * to also call setCategorizedModel() class to enable it, since the categorization
29  * is disabled by default.
30  *
31  * @see KCategorizedView
32  *
33  * @author Rafael Fernández López <[email protected]>
34  */
36 {
37 public:
39  // Note: use printf "0x%08X\n" $(($RANDOM*$RANDOM))
40  // to define additional roles.
41  CategoryDisplayRole = 0x17CE990A, ///< This role is used for asking the category to a given index
42 
43  CategorySortRole = 0x27857E60, ///< This role is used for sorting categories. You can return a
44  ///< string or a long long value. Strings will be sorted alphabetically
45  ///< while long long will be sorted by their value. Please note that this
46  ///< value won't be shown on the view, is only for sorting purposes. What will
47  ///< be shown as "Category" on the view will be asked with the role
48  ///< CategoryDisplayRole.
49  };
50 
51  KCategorizedSortFilterProxyModel(QObject *parent = nullptr);
53 
54  /**
55  * Overridden from QSortFilterProxyModel. Sorts the source model using
56  * @p column for the given @p order.
57  */
58  void sort(int column, Qt::SortOrder order = Qt::AscendingOrder) override;
59 
60  /**
61  * @return whether the model is categorized or not. Disabled by default.
62  */
63  bool isCategorizedModel() const;
64 
65  /**
66  * Enables or disables the categorization feature.
67  *
68  * @param categorizedModel whether to enable or disable the categorization feature.
69  */
70  void setCategorizedModel(bool categorizedModel);
71 
72  /**
73  * @return the column being used for sorting.
74  */
75  int sortColumn() const;
76 
77  /**
78  * @return the sort order being used for sorting.
79  */
80  Qt::SortOrder sortOrder() const;
81 
82  /**
83  * Set if the sorting using CategorySortRole will use a natural comparison
84  * in the case that strings were returned. If enabled, QCollator
85  * will be used for sorting.
86  *
87  * @param sortCategoriesByNaturalComparison whether to sort using a natural comparison or not.
88  */
89  void setSortCategoriesByNaturalComparison(bool sortCategoriesByNaturalComparison);
90 
91  /**
92  * @return whether it is being used a natural comparison for sorting. Enabled by default.
93  */
94  bool sortCategoriesByNaturalComparison() const;
95 
96 #if KITEMVIEWS_ENABLE_DEPRECATED_SINCE(4, 4)
97  /**
98  * Does a natural comparing of the strings. A negative value is returned if \a a
99  * is smaller than \a b. A positive value is returned if \a a is greater than \a b. 0
100  * is returned if both values are equal.
101  * @deprecated Since 4.4. Use QCollator instead.
102  */
103  KITEMVIEWS_DEPRECATED_VERSION(4, 4, "Use QCollator")
104  static int naturalCompare(const QString &a, const QString &b);
105 #endif
106 
107 protected:
108  /**
109  * Overridden from QSortFilterProxyModel. If you are subclassing
110  * KCategorizedSortFilterProxyModel, you will probably not need to reimplement this
111  * method.
112  *
113  * It calls compareCategories() to sort by category. If the both items are in the
114  * same category (i.e. compareCategories returns 0), then subSortLessThan is called.
115  *
116  * @return Returns true if the item @p left is less than the item @p right when sorting.
117  *
118  * @warning You usually won't need to reimplement this method when subclassing
119  * from KCategorizedSortFilterProxyModel.
120  */
121  bool lessThan(const QModelIndex &left, const QModelIndex &right) const override;
122 
123  /**
124  * This method has a similar purpose as lessThan() has on QSortFilterProxyModel.
125  * It is used for sorting items that are in the same category.
126  *
127  * @return Returns true if the item @p left is less than the item @p right when sorting.
128  */
129  virtual bool subSortLessThan(const QModelIndex &left, const QModelIndex &right) const;
130 
131  /**
132  * This method compares the category of the @p left index with the category
133  * of the @p right index.
134  *
135  * Internally and if not reimplemented, this method will ask for @p left and
136  * @p right models for role CategorySortRole. In order to correctly sort
137  * categories, the data() method of the model should return a qlonglong (or numeric) value, or
138  * a QString object. QString objects will be sorted with QString::localeAwareCompare if
139  * sortCategoriesByNaturalComparison() is true.
140  *
141  * @note Please have present that:
142  * QString(QChar(QChar::ObjectReplacementCharacter)) >
143  * QString(QChar(QChar::ReplacementCharacter)) >
144  * [ all possible strings ] >
145  * QString();
146  *
147  * This means that QString() will be sorted the first one, while
148  * QString(QChar(QChar::ObjectReplacementCharacter)) and
149  * QString(QChar(QChar::ReplacementCharacter)) will be sorted in last
150  * position.
151  *
152  * @warning Please note that data() method of the model should return always
153  * information of the same type. If you return a QString for an index,
154  * you should return always QStrings for all indexes for role CategorySortRole
155  * in order to correctly sort categories. You can't mix by returning
156  * a QString for one index, and a qlonglong for other.
157  *
158  * @note If you need a more complex layout, you will have to reimplement this
159  * method.
160  *
161  * @return A negative value if the category of @p left should be placed before the
162  * category of @p right. 0 if @p left and @p right are on the same category, and
163  * a positive value if the category of @p left should be placed after the
164  * category of @p right.
165  */
166  virtual int compareCategories(const QModelIndex &left, const QModelIndex &right) const;
167 
168 private:
169  std::unique_ptr<KCategorizedSortFilterProxyModelPrivate> const d;
170 };
171 
172 #endif // KCATEGORIZEDSORTFILTERPROXYMODEL_H
SortOrder
virtual void sort(int column, Qt::SortOrder order) override
virtual bool lessThan(const QModelIndex &source_left, const QModelIndex &source_right) const const
Qt::SortOrder sortOrder() const const
int sortColumn() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:17:18 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.