1/*
2 Copyright 2008 Ingo Klöcker <kloecker@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_COLLECTIONREQUESTER_H
21#define AKONADI_COLLECTIONREQUESTER_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/collection.h>
26#include <akonadi/collectiondialog.h>
27#include <khbox.h>
28
29namespace Akonadi {
30
31/**
32 * @short A widget to request an Akonadi collection from the user.
33 *
34 * This class is a widget showing a read-only lineedit displaying
35 * the currently chosen collection and a button invoking a dialog
36 * for choosing a collection.
37 *
38 * Example:
39 *
40 * @code
41 *
42 * // create a collection requester to select a collection of contacts
43 * Akonadi::CollectionRequester requester( Akonadi::Collection::root(), this );
44 * requester.setMimeTypeFilter( QStringList() << QString( "text/directory" ) );
45 *
46 * ...
47 *
48 * const Akonadi::Collection collection = requester.collection();
49 * if ( collection.isValid() ) {
50 * ...
51 * }
52 *
53 * @endcode
54 *
55 * @author Ingo Klöcker <kloecker@kde.org>
56 * @since 4.3
57 */
58class AKONADI_EXPORT CollectionRequester : public KHBox
59{
60 Q_OBJECT
61 Q_DISABLE_COPY(CollectionRequester)
62
63public:
64 /**
65 * Creates a collection requester.
66 *
67 * @param parent The parent widget.
68 */
69 explicit CollectionRequester(QWidget *parent = 0);
70
71 /**
72 * Creates a collection requester with an initial @p collection.
73 *
74 * @param collection The initial collection.
75 * @param parent The parent widget.
76 */
77 explicit CollectionRequester(const Akonadi::Collection &collection, QWidget *parent = 0);
78
79 /**
80 * Destroys the collection requester.
81 */
82 ~CollectionRequester();
83
84 /**
85 * Returns the currently chosen collection, or an empty collection if none
86 * none was chosen.
87 */
88 Akonadi::Collection collection() const;
89
90 /**
91 * Sets the mime types any of which the selected collection shall support.
92 */
93 void setMimeTypeFilter(const QStringList &mimeTypes);
94
95 /**
96 * Returns the mime types any of which the selected collection shall support.
97 */
98 QStringList mimeTypeFilter() const;
99
100 /**
101 * Sets the access @p rights that the listed collections shall match with.
102 * @param rights the access rights to set
103 * @since 4.4
104 */
105 void setAccessRightsFilter(Collection::Rights rights);
106
107 /**
108 * Returns the access rights that the listed collections shall match with.
109 * @since 4.4
110 */
111 Collection::Rights accessRightsFilter() const;
112
113 /**
114 * @param options new collection dialog options
115 */
116 void changeCollectionDialogOptions(CollectionDialog::CollectionDialogOptions options);
117
118protected:
119 void changeEvent(QEvent * event);
120
121public Q_SLOTS:
122 /**
123 * Sets the @p collection of the requester.
124 */
125 void setCollection(const Akonadi::Collection &collection);
126
127Q_SIGNALS:
128 /**
129 * This signal is emitted when the selected collection has changed.
130 *
131 * @param collection The selected collection.
132 *
133 * @since 4.5
134 */
135 void collectionChanged(const Akonadi::Collection &collection);
136
137private:
138 class Private;
139 Private *const d;
140
141 Q_PRIVATE_SLOT(d, void _k_slotOpenDialog())
142 Q_PRIVATE_SLOT(d, void _k_collectionReceived(KJob *job))
143 Q_PRIVATE_SLOT(d, void _k_collectionsNamesReceived(KJob *job))
144};
145
146} // namespace Akonadi
147
148#endif // AKONADI_COLLECTIONREQUESTER_H
149