KItemViews

kcategorizedsortfilterproxymodel.h
1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2007 Rafael Fernández López <ereslibre@kde.org>
4 SPDX-FileCopyrightText: 2007 John Tapsell <tapsell@kde.org>
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>
16class KCategorizedSortFilterProxyModelPrivate;
17
18class 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 <ereslibre@kde.org>
34 */
36{
37public:
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
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 */
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
96protected:
97 /**
98 * Overridden from QSortFilterProxyModel. If you are subclassing
99 * KCategorizedSortFilterProxyModel, you will probably not need to reimplement this
100 * method.
101 *
102 * It calls compareCategories() to sort by category. If the both items are in the
103 * same category (i.e. compareCategories returns 0), then subSortLessThan is called.
104 *
105 * @return Returns true if the item @p left is less than the item @p right when sorting.
106 *
107 * @warning You usually won't need to reimplement this method when subclassing
108 * from KCategorizedSortFilterProxyModel.
109 */
110 bool lessThan(const QModelIndex &left, const QModelIndex &right) const override;
111
112 /**
113 * This method has a similar purpose as lessThan() has on QSortFilterProxyModel.
114 * It is used for sorting items that are in the same category.
115 *
116 * @return Returns true if the item @p left is less than the item @p right when sorting.
117 */
118 virtual bool subSortLessThan(const QModelIndex &left, const QModelIndex &right) const;
119
120 /**
121 * This method compares the category of the @p left index with the category
122 * of the @p right index.
123 *
124 * Internally and if not reimplemented, this method will ask for @p left and
125 * @p right models for role CategorySortRole. In order to correctly sort
126 * categories, the data() method of the model should return a qlonglong (or numeric) value, or
127 * a QString object. QString objects will be sorted with QString::localeAwareCompare if
128 * sortCategoriesByNaturalComparison() is true.
129 *
130 * @note Please have present that:
131 * QString(QChar(QChar::ObjectReplacementCharacter)) >
132 * QString(QChar(QChar::ReplacementCharacter)) >
133 * [ all possible strings ] >
134 * QString();
135 *
136 * This means that QString() will be sorted the first one, while
137 * QString(QChar(QChar::ObjectReplacementCharacter)) and
138 * QString(QChar(QChar::ReplacementCharacter)) will be sorted in last
139 * position.
140 *
141 * @warning Please note that data() method of the model should return always
142 * information of the same type. If you return a QString for an index,
143 * you should return always QStrings for all indexes for role CategorySortRole
144 * in order to correctly sort categories. You can't mix by returning
145 * a QString for one index, and a qlonglong for other.
146 *
147 * @note If you need a more complex layout, you will have to reimplement this
148 * method.
149 *
150 * @return A negative value if the category of @p left should be placed before the
151 * category of @p right. 0 if @p left and @p right are on the same category, and
152 * a positive value if the category of @p left should be placed after the
153 * category of @p right.
154 */
155 virtual int compareCategories(const QModelIndex &left, const QModelIndex &right) const;
156
157private:
158 std::unique_ptr<KCategorizedSortFilterProxyModelPrivate> const d;
159};
160
161#endif // KCATEGORIZEDSORTFILTERPROXYMODEL_H
This class lets you categorize a view.
virtual bool lessThan(const QModelIndex &source_left, const QModelIndex &source_right) const const
virtual void sort(int column, Qt::SortOrder order) override
int sortColumn() const const
Qt::SortOrder sortOrder() const const
SortOrder
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:44:02 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.