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_COLLECTIONPROPERTIESPAGE_H
21#define AKONADI_COLLECTIONPROPERTIESPAGE_H
22
23#include "akonadi_export.h"
24
25#include <QWidget>
26
27namespace Akonadi {
28
29class Collection;
30
31/**
32 * @short A single page in a collection properties dialog.
33 *
34 * The collection properties dialog can be extended by custom
35 * collection properties pages, which provide gui elements for
36 * viewing and changing collection attributes.
37 *
38 * The following example shows how to create a simple collection
39 * properties page for the secrecy attribute from the Akonadi::Attribute
40 * example.
41 *
42 * @code
43 *
44 * class SecrecyPage : public CollectionPropertiesPage
45 * {
46 * public:
47 * SecrecyPage( QWidget *parent = 0 )
48 * : CollectionPropertiesPage( parent )
49 * {
50 * QVBoxLayout *layout = new QVBoxLayout( this );
51 *
52 * mSecrecy = new QComboBox( this );
53 * mSecrecy->addItem( "Public" );
54 * mSecrecy->addItem( "Private" );
55 * mSecrecy->addItem( "Confidential" );
56 *
57 * layout->addWidget( new QLabel( "Secrecy:" ) );
58 * layout->addWidget( mSecrecy );
59 *
60 * setPageTitle( i18n( "Secrecy" ) );
61 * }
62 *
63 * void load( const Collection &collection )
64 * {
65 * SecrecyAttribute *attr = collection.attribute( "secrecy" );
66 *
67 * switch ( attr->secrecy() ) {
68 * case SecrecyAttribute::Public: mSecrecy->setCurrentIndex( 0 ); break;
69 * case SecrecyAttribute::Private: mSecrecy->setCurrentIndex( 1 ); break;
70 * case SecrecyAttribute::Confidential: mSecrecy->setCurrentIndex( 2 ); break;
71 * }
72 * }
73 *
74 * void save( Collection &collection )
75 * {
76 * SecrecyAttribute *attr = collection.attribute( "secrecy" );
77 *
78 * switch ( mSecrecy->currentIndex() ) {
79 * case 0: attr->setSecrecy( SecrecyAttribute::Public ); break;
80 * case 1: attr->setSecrecy( SecrecyAttribute::Private ); break;
81 * case 2: attr->setSecrecy( SecrecyAttribute::Confidential ); break;
82 * }
83 * }
84 *
85 * bool canHandle( const Collection &collection ) const
86 * {
87 * return collection.hasAttribute( "secrecy" );
88 * }
89 * };
90 *
91 * AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY( SecrecyPageFactory, SecrecyPage )
92 *
93 * @endcode
94 *
95 * @see Akonadi::CollectionPropertiesDialog, Akonadi::CollectionPropertiesPageFactory
96 *
97 * @author Volker Krause <vkrause@kde.org>
98 */
99class AKONADI_EXPORT CollectionPropertiesPage : public QWidget
100{
101 Q_OBJECT
102public:
103 /**
104 * Creates a new collection properties page.
105 *
106 * @param parent The parent widget.
107 */
108 explicit CollectionPropertiesPage(QWidget *parent = 0);
109
110 /**
111 * Destroys the collection properties page.
112 */
113 ~CollectionPropertiesPage();
114
115 /**
116 * Loads the page content from the given collection.
117 *
118 * @param collection The collection to load.
119 */
120 virtual void load(const Collection &collection) = 0;
121
122 /**
123 * Saves page content to the given collection.
124 *
125 * @param collection Reference to the collection to save to.
126 */
127 virtual void save(Collection &collection) = 0;
128
129 /**
130 * Checks if this page can actually handle the given collection.
131 *
132 * Returns @c true if the collection can be handled, @c false otherwise
133 * The default implementation returns always @c true. When @c false is returned
134 * this page is not shown in the properties dialog.
135 * @param collection The collection to check.
136 */
137 virtual bool canHandle(const Collection &collection) const;
138
139 /**
140 * Sets the page title.
141 *
142 * @param title Translated, preferbly short tab title.
143 */
144 void setPageTitle(const QString &title);
145
146 /**
147 * Returns the page title.
148 */
149 QString pageTitle() const;
150
151private:
152 //@cond PRIVATE
153 class Private;
154 Private *const d;
155 //@endcond
156};
157
158/**
159 * @short A factory class for collection properties dialog pages.
160 *
161 * The factory encapsulates the creation of the collection properties
162 * dialog page.
163 * You can use the AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY macro
164 * to create a factory class automatically.
165 *
166 * @author Volker Krause <vkrause@kde.org>
167 */
168class AKONADI_EXPORT CollectionPropertiesPageFactory
169{
170public:
171 /**
172 * Destroys the collection properties page factory.
173 */
174 virtual ~CollectionPropertiesPageFactory();
175
176 /**
177 * Returns the actual page widget.
178 *
179 * @param parent The parent widget.
180 */
181 virtual CollectionPropertiesPage *createWidget(QWidget *parent = 0) const = 0;
182};
183
184/**
185 * @def AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY
186 *
187 * The AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY macro can be used to
188 * create a factory for a custom collection properties page.
189 *
190 * @code
191 *
192 * class MyPage : public Akonadi::CollectionPropertiesPage
193 * {
194 * ...
195 * }
196 *
197 * AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY( MyPageFactory, MyPage )
198 *
199 * @endcode
200 *
201 * The macro takes two arguments, where the first one is the name of the
202 * factory class that shall be created and the second arguments is the name
203 * of the custom collection properties page class.
204 *
205 * @ingroup AkonadiMacros
206 */
207#define AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY(factoryName, className) \
208class factoryName : public Akonadi::CollectionPropertiesPageFactory \
209{ \
210 public: \
211 inline Akonadi::CollectionPropertiesPage *createWidget( QWidget *parent = 0 ) const \
212 { \
213 return new className( parent ); \
214 } \
215};
216
217}
218
219#endif
220