Akonadi

collectiondialog.h
1 /*
2  SPDX-FileCopyrightText: 2008 Ingo Klöcker <[email protected]>
3  SPDX-FileCopyrightText: 2010-2022 Laurent Montel <[email protected]>
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 
19 namespace Akonadi
20 {
21 class 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 <[email protected]>
54  * @since 4.3
55  */
56 class AKONADIWIDGETS_EXPORT CollectionDialog : public QDialog
57 {
58  Q_OBJECT
59  Q_DISABLE_COPY(CollectionDialog)
60 
61 public:
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  */
110  ~CollectionDialog() override;
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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT Akonadi::Collection selectedCollection() const;
172 
173  /**
174  * Returns the list of selected collections.
175  */
176  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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 
199 private:
200  /// @cond PRIVATE
201  std::unique_ptr<CollectionDialogPrivate> const d;
202  /// @endcond
203 };
204 
205 } // namespace Akonadi
206 
Represents a collection of PIM items.
Definition: collection.h:61
A collection selection dialog.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jul 2 2022 06:41:47 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.