1/*
2 Copyright (c) 2008 Volker Krause <vkrause@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_COLLECTIONPROPERTIESDIALOG_H
21#define AKONADI_COLLECTIONPROPERTIESDIALOG_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/collectionpropertiespage.h>
26
27#include <kdialog.h>
28
29namespace Akonadi {
30
31class Collection;
32
33/**
34 * @short A generic and extensible dialog for collection properties.
35 *
36 * This dialog allows you to show or modify the properties of a collection.
37 *
38 * @code
39 *
40 * Akonadi::Collection collection = ...
41 *
42 * CollectionPropertiesDialog dlg( collection, this );
43 * dlg.exec();
44 *
45 * @endcode
46 *
47 * It can be extended by custom pages, which contains gui elements for custom
48 * properties.
49 *
50 * @see Akonadi::CollectionPropertiesPage
51 *
52 * @author Volker Krause <vkrause@kde.org>
53 */
54class AKONADI_EXPORT CollectionPropertiesDialog : public KDialog
55{
56 Q_OBJECT
57public:
58 /**
59 * Enumerates the registered default pages which can be displayed.
60 *
61 * @since 4.7
62 */
63 enum DefaultPage {
64 GeneralPage, //!< General properties page
65 CachePage //!< Cache properties page
66 };
67
68 /**
69 * Creates a new collection properties dialog.
70 *
71 * @param collection The collection which properties should be shown.
72 * @param parent The parent widget.
73 */
74 explicit CollectionPropertiesDialog(const Collection &collection, QWidget *parent = 0);
75
76 /**
77 * Creates a new collection properties dialog.
78 *
79 * This constructor allows to specify the subset of registered pages that will
80 * be shown as well as their order. The pages have to set an objectName in their
81 * constructor to make it work. If an empty list is passed, all registered pages
82 * will be loaded. Use defaultPageObjectName() to fetch the object name for a
83 * registered default page.
84 *
85 * @param collection The collection which properties should be shown.
86 * @param pages The object names of the pages that shall be loaded.
87 * @param parent The parent widget.
88 *
89 * @since 4.6
90 */
91 CollectionPropertiesDialog(const Collection &collection, const QStringList &pages, QWidget *parent = 0);
92
93 /**
94 * Destroys the collection properties dialog.
95 *
96 * @note Never call manually, the dialog is deleted automatically once all changes
97 * are written back to the Akonadi storage.
98 */
99 ~CollectionPropertiesDialog();
100
101 /**
102 * Register custom pages for the collection properties dialog.
103 *
104 * @param factory The properties page factory that provides the custom page.
105 *
106 * @see Akonadi::CollectionPropertiesPageFactory
107 */
108 static void registerPage(CollectionPropertiesPageFactory *factory);
109
110 /**
111 * Sets whether to @p use default page or not.
112 *
113 * @since 4.4
114 * @param use mode of default page's usage
115 */
116 static void useDefaultPage(bool use);
117
118 /**
119 * Returns the object name of one of the dialog's registered default pages.
120 * The object name may be used in the QStringList constructor parameter to
121 * specify which default pages should be shown.
122 *
123 * @param page the desired page
124 * @return the page's object name
125 *
126 * @since 4.7
127 */
128 static QString defaultPageObjectName(DefaultPage page);
129
130 /**
131 * Sets the page to be shown in the tab widget.
132 *
133 * @param name The object name of the page that is to be shown.
134 *
135 * @since 4.10
136 */
137 void setCurrentPage(const QString &name);
138
139private:
140 //@cond PRIVATE
141 class Private;
142 Private *const d;
143
144 Q_PRIVATE_SLOT(d, void save())
145 Q_PRIVATE_SLOT(d, void saveResult(KJob *))
146 //@endcond
147};
148
149}
150
151#endif
152