Akonadi

collectiondialog.h
1/*
2 SPDX-FileCopyrightText: 2008 Ingo Klöcker <kloecker@kde.org>
3 SPDX-FileCopyrightText: 2010-2024 Laurent Montel <montel@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#pragma once
9
10#include "akonadiwidgets_export.h"
11// AkonadiCore
12#include "akonadi/collection.h"
13
14#include <QAbstractItemView>
15#include <QDialog>
16
17#include <memory>
18
19namespace Akonadi
20{
21class CollectionDialogPrivate;
22
23/**
24 * @short A collection selection dialog.
25 *
26 * Provides a dialog that lists collections that are available
27 * on the Akonadi storage and allows the selection of one or multiple
28 * collections.
29 *
30 * The list of shown collections can be filtered by mime type and access
31 * rights. Note that mime types are not enabled by default, so
32 * setMimeTypeFilter() must be called to enable the desired mime types.
33 *
34 * Example:
35 *
36 * @code
37 *
38 * using namespace Akonadi;
39 *
40 * // Show the user a dialog to select a writable collection of contacts
41 * CollectionDialog dlg( this );
42 * dlg.setMimeTypeFilter( QStringList() << KContacts::Addressee::mimeType() );
43 * dlg.setAccessRightsFilter( Collection::CanCreateItem );
44 * dlg.setDescription( i18n( "Select an address book for saving:" ) );
45 *
46 * if ( dlg.exec() ) {
47 * const Collection collection = dlg.selectedCollection();
48 * ...
49 * }
50 *
51 * @endcode
52 *
53 * @author Ingo Klöcker <kloecker@kde.org>
54 * @since 4.3
55 */
56class AKONADIWIDGETS_EXPORT CollectionDialog : public QDialog
57{
58 Q_OBJECT
59 Q_DISABLE_COPY(CollectionDialog)
60
61public:
62 /* @since 4.6
63 */
64 enum CollectionDialogOption {
65 None = 0,
66 AllowToCreateNewChildCollection = 1,
67 KeepTreeExpanded = 2,
68 };
69
70 Q_DECLARE_FLAGS(CollectionDialogOptions, CollectionDialogOption)
71
72 /**
73 * Creates a new collection dialog.
74 *
75 * @param parent The parent widget.
76 */
77 explicit CollectionDialog(QWidget *parent = nullptr);
78
79 /**
80 * Creates a new collection dialog with a custom @p model.
81 *
82 * The filtering by content mime type and access rights is done
83 * on top of the custom model.
84 *
85 * @param model The custom model to use.
86 * @param parent The parent widget.
87 *
88 * @since 4.4
89 */
90 explicit CollectionDialog(QAbstractItemModel *model, QWidget *parent = nullptr);
91
92 /**
93 * Creates a new collection dialog with a custom @p model.
94 *
95 * The filtering by content mime type and access rights is done
96 * on top of the custom model.
97 *
98 * @param options The collection dialog options.
99 * @param model The custom model to use.
100 * @param parent The parent widget.
101 *
102 * @since 4.6
103 */
104
105 explicit CollectionDialog(CollectionDialogOptions options, QAbstractItemModel *model = nullptr, QWidget *parent = nullptr);
106
107 /**
108 * Destroys the collection dialog.
109 */
111
112 /**
113 * Sets the mime types any of which the selected collection(s) shall support.
114 * Note that mime types are not enabled by default.
115 * @param mimeTypes MIME type filter values
116 */
117 void setMimeTypeFilter(const QStringList &mimeTypes);
118
119 /**
120 * Returns the mime types any of which the selected collection(s) shall support.
121 */
122 [[nodiscard]] QStringList mimeTypeFilter() const;
123
124 /**
125 * Sets the access @p rights that the listed collections shall match with.
126 * @param rights access rights filter values
127 * @since 4.4
128 */
129 void setAccessRightsFilter(Collection::Rights rights);
130
131 /**
132 * Sets the access @p rights that the listed collections shall match with.
133 *
134 * @since 4.4
135 */
136 [[nodiscard]] Collection::Rights accessRightsFilter() const;
137
138 /**
139 * Sets the @p text that will be shown in the dialog.
140 * @param text the dialog's description text
141 * @since 4.4
142 */
143 void setDescription(const QString &text);
144
145 /**
146 * Sets the @p collection that shall be selected by default.
147 * @param collection the dialog's pre-selected collection
148 * @since 4.4
149 */
150 void setDefaultCollection(const Collection &collection);
151
152 /**
153 * Sets the selection mode. The initial default mode is
154 * QAbstractItemView::SingleSelection.
155 * @param mode the selection mode to use
156 * @see QAbstractItemView::setSelectionMode()
157 */
158 void setSelectionMode(QAbstractItemView::SelectionMode mode);
159
160 /**
161 * Returns the selection mode.
162 * @see QAbstractItemView::selectionMode()
163 */
164 [[nodiscard]] QAbstractItemView::SelectionMode selectionMode() const;
165
166 /**
167 * Returns the selected collection if the selection mode is
168 * QAbstractItemView::SingleSelection. If another selection mode was set,
169 * or nothing is selected, an invalid collection is returned.
170 */
171 [[nodiscard]] Akonadi::Collection selectedCollection() const;
172
173 /**
174 * Returns the list of selected collections.
175 */
176 [[nodiscard]] Akonadi::Collection::List selectedCollections() const;
177
178 /**
179 * Change collection dialog options.
180 * @param options the collection dialog options to change
181 * @since 4.6
182 */
183 void changeCollectionDialogOptions(CollectionDialogOptions options);
184
185 /**
186 * @since 4.13
187 */
188 void setUseFolderByDefault(bool b);
189 /**
190 * @since 4.13
191 */
192 [[nodiscard]] bool useFolderByDefault() const;
193 /**
194 * Allow to specify collection content mimetype when we create new one.
195 * @since 4.14.6
196 */
197 void setContentMimeTypes(const QStringList &mimetypes);
198
199private:
200 /// @cond PRIVATE
201 std::unique_ptr<CollectionDialogPrivate> const d;
202 /// @endcond
203};
204
205} // namespace Akonadi
A collection selection dialog.
~CollectionDialog() override
Destroys the collection dialog.
Represents a collection of PIM items.
Definition collection.h:62
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 4 2024 11:57:21 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.