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 | |
27 | namespace Akonadi { |
28 | |
29 | class 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 | */ |
99 | class AKONADI_EXPORT CollectionPropertiesPage : public QWidget |
100 | { |
101 | Q_OBJECT |
102 | public: |
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 | |
151 | private: |
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 | */ |
168 | class AKONADI_EXPORT CollectionPropertiesPageFactory |
169 | { |
170 | public: |
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) \ |
208 | class 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 | |