1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
/***************************************************************************
* Copyright (C) 2011 by Peter Penz <[email protected]> *
* *
* Based on the Itemviews NG project from Trolltech Labs: *
* http://qt.gitorious.org/qt-labs/itemviews-ng *
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; either version 2 of the License, or *
* (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* You should have received a copy of the GNU General Public License *
* along with this program; if not, write to the *
* Free Software Foundation, Inc., *
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA *
***************************************************************************/
#ifndef KITEMMODELBASE_H
#define KITEMMODELBASE_H
#include <libdolphin_export.h>
#include <QHash>
#include <QObject>
#include <QSet>
#include <QVariant>
struct KItemRange
{
KItemRange(int index, int count);
int index;
int count;
bool operator == (const KItemRange& other) const;
};
typedef QList<KItemRange> KItemRangeList;
/**
* @brief Base class for model implementations used by KItemListView and KItemListController.
*
* A item-model consists of a variable number of items. The number of items
* is given by KItemModelBase::count(). The data of an item is accessed by a unique index
* with KItemModelBase::data(). The indexes are integer-values counting from 0 to the
* KItemModelBase::count() - 1.
*
* One item consists of a variable number of role/value-pairs.
*
* A model can optionally provide sorting- and/or grouping-capabilities.
*/
class LIBDOLPHINPRIVATE_EXPORT KItemModelBase : public QObject
{
Q_OBJECT
public:
KItemModelBase(QObject* parent = 0);
KItemModelBase(const QByteArray& groupRole, const QByteArray& sortRole, QObject* parent = 0);
virtual ~KItemModelBase();
/** @return The number of items. */
virtual int count() const = 0;
virtual QHash<QByteArray, QVariant> data(int index) const = 0;
/**
* Sets the data for the item at \a index to the given \a values. Returns true
* if the data was set on the item; returns false otherwise.
*
* The default implementation does not set the data, and will always return
* false.
*/
virtual bool setData(int index, const QHash<QByteArray, QVariant>& values);
/**
* @return True if the model supports grouping of data. Per default false is returned.
* If the model should support grouping it is necessary to overwrite
* this method to return true and to implement KItemModelBase::onGroupRoleChanged().
*/
virtual bool supportsGrouping() const;
/**
* Sets the group-role to \a role. The method KItemModelBase::onGroupRoleChanged() will be
* called so that model-implementations can react on the group-role change. Afterwards the
* signal groupRoleChanged() will be emitted.
*/
void setGroupRole(const QByteArray& role);
QByteArray groupRole() const;
/**
* @return True if the model supports sorting of data. Per default false is returned.
* If the model should support sorting it is necessary to overwrite
* this method to return true and to implement KItemModelBase::onSortRoleChanged().
*/
virtual bool supportsSorting() const;
/**
* Sets the sor-role to \a role. The method KItemModelBase::onSortRoleChanged() will be
* called so that model-implementations can react on the sort-role change. Afterwards the
* signal sortRoleChanged() will be emitted.
*/
void setSortRole(const QByteArray& role);
QByteArray sortRole() const;
virtual QString roleDescription(const QByteArray& role) const;
signals:
/**
* Is emitted if one or more items have been inserted. Each item-range consists
* of:
* - an index where items have been inserted
* - the number of inserted items.
* The index of each item-range represents the index of the model
* before the items have been inserted.
*
* For the item-ranges it is assured that:
* - They don't overlap
* - The index of item-range n is smaller than the index of item-range n + 1.
*/
void itemsInserted(const KItemRangeList& itemRanges);
/**
* Is emitted if one or more items have been removed. Each item-range consists
* of:
* - an index where items have been inserted
* - the number of inserted items.
* The index of each item-range represents the index of the model
* before the items have been removed.
*
* For the item-ranges it is assured that:
* - They don't overlap
* - The index of item-range n is smaller than the index of item-range n + 1.
*/
void itemsRemoved(const KItemRangeList& itemRanges);
/**
* Is emitted if one ore more items get moved.
* @param itemRanges Item-ranges that get moved to a new position.
* @param movedToIndexes New position of the ranges.
* It is assured that the itemRanges list has the same size as the movedToIndexes list.
*
* For the item-ranges it is assured that:
* - They don't overlap
* - The index of item-range n is smaller than the index of item-range n + 1.
*/
void itemsMoved(const KItemRangeList& itemRanges, const QList<int> movedToIndexes);
void itemsChanged(const KItemRangeList& itemRanges, const QSet<QByteArray>& roles);
void groupRoleChanged(const QByteArray& current, const QByteArray& previous);
void sortRoleChanged(const QByteArray& current, const QByteArray& previous);
protected:
/**
* Is invoked if the group role has been changed by KItemModelBase::setGroupRole(). Allows
* to react on the changed group role before the signal groupRoleChanged() will be emitted.
* The implementation must assure that the items are sorted in a way that they are grouped
* by the role given by \a current. Usually the most efficient way is to emit a
* itemsRemoved() signal for all items, reorder the items internally and to emit a
* itemsInserted() signal afterwards.
*/
virtual void onGroupRoleChanged(const QByteArray& current, const QByteArray& previous);
/**
* Is invoked if the sort role has been changed by KItemModelBase::setSortRole(). Allows
* to react on the changed sort role before the signal sortRoleChanged() will be emitted.
* The implementation must assure that the items are sorted by the role given by \a current.
* Usually the most efficient way is to emit a
* itemsRemoved() signal for all items, reorder the items internally and to emit a
* itemsInserted() signal afterwards.
*/
virtual void onSortRoleChanged(const QByteArray& current, const QByteArray& previous);
private:
QByteArray m_groupRole;
QByteArray m_sortRole;
};
#endif
|
