1/*
2 Copyright (c) 2009 Kevin Ottens <ervin@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_FAVORITECOLLECTIONSMODEL_H
21#define AKONADI_FAVORITECOLLECTIONSMODEL_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/selectionproxymodel.h>
26
27#include <akonadi/collection.h>
28
29class KConfigGroup;
30class KJob;
31
32namespace Akonadi {
33
34class EntityTreeModel;
35
36/**
37 * @short A model that lists a set of favorite collections.
38 *
39 * In some applications you want to provide fast access to a list
40 * of often used collections (e.g. Inboxes from different email accounts
41 * in a mail application). Therefor you can use the FavoriteCollectionsModel
42 * which stores the list of favorite collections in a given configuration
43 * file.
44 *
45 * Example:
46 *
47 * @code
48 *
49 * using namespace Akonadi;
50 *
51 * EntityTreeModel *sourceModel = new EntityTreeModel( ... );
52 *
53 * const KConfigGroup group = KGlobal::config()->group( "Favorite Collections" );
54 *
55 * FavoriteCollectionsModel *model = new FavoriteCollectionsModel( sourceModel, group, this );
56 *
57 * EntityListView *view = new EntityListView( this );
58 * view->setModel( model );
59 *
60 * @endcode
61 *
62 * @author Kevin Ottens <ervin@kde.org>
63 * @since 4.4
64 */
65//TODO_KDE5: Make this a KRecursiveFilterProxyModel instead of a SelectionProxyModel
66class AKONADI_EXPORT FavoriteCollectionsModel : public Akonadi::SelectionProxyModel
67{
68 Q_OBJECT
69
70public:
71 /**
72 * Creates a new favorite collections model.
73 *
74 * @param model The source model where the favorite collections
75 * come from.
76 * @param group The config group that shall be used to save the
77 * selection of favorite collections.
78 * @param parent The parent object.
79 */
80 FavoriteCollectionsModel(QAbstractItemModel *model, const KConfigGroup &group, QObject *parent = 0);
81
82 /**
83 * Destroys the favorite collections model.
84 */
85 virtual ~FavoriteCollectionsModel();
86
87 /**
88 * Returns the list of favorite collections.
89 * @deprecated Use collectionIds instead.
90 */
91 Collection::List collections() const;
92
93 /**
94 * Returns the list of ids of favorite collections set on the FavoriteCollectionsModel.
95 *
96 * Note that if you want Collections with actual data
97 * you should use something like this instead:
98 *
99 * @code
100 * FavoriteCollectionsModel* favs = getFavsModel();
101 * Collection::List cols;
102 * const int rowCount = favs->rowCount();
103 * for (int row = 0; row < rowcount; ++row) {
104 * static const int column = 0;
105 * const QModelIndex index = favs->index(row, column);
106 * const Collection col = index.data(EntityTreeModel::CollectionRole).value<Collection>();
107 * cols << col;
108 * }
109 * @endcode
110 *
111 * Note that due to the asynchronous nature of the model, this method returns collection ids
112 * of collections which may not be in the model yet. If you want the ids of the collections
113 * that are actually in the model, use a loop similar to above with the CollectionIdRole.
114 */
115 QList<Collection::Id> collectionIds() const;
116
117 /**
118 * Return associate label for collection
119 */
120 QString favoriteLabel(const Akonadi::Collection &col);
121
122 virtual QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const;
123 virtual bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole);
124 virtual QVariant headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const;
125 virtual bool dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent);
126 virtual QStringList mimeTypes() const;
127 virtual Qt::ItemFlags flags(const QModelIndex &index) const;
128
129public Q_SLOTS:
130 /**
131 * Sets the @p collections as favorite collections.
132 */
133 void setCollections(const Collection::List &collections);
134
135 /**
136 * Adds a @p collection to the list of favorite collections.
137 */
138 void addCollection(const Collection &collection);
139
140 /**
141 * Removes a @p collection from the list of favorite collections.
142 */
143 void removeCollection(const Collection &collection);
144
145 /**
146 * Sets a custom @p label that will be used when showing the
147 * favorite @p collection.
148 */
149 void setFavoriteLabel(const Collection &collection, const QString &label);
150
151private Q_SLOTS:
152 void pasteJobDone(KJob *job);
153
154private:
155 //@cond PRIVATE
156 using KSelectionProxyModel::setSourceModel;
157
158 class Private;
159 Private *const d;
160
161 Q_PRIVATE_SLOT(d, void reload())
162 Q_PRIVATE_SLOT(d, void rowsInserted(QModelIndex, int, int))
163 Q_PRIVATE_SLOT(d, void dataChanged(QModelIndex, QModelIndex))
164 //@endcond
165};
166
167}
168
169#endif
170