author | zautrix <zautrix> | 2004-06-26 19:01:18 (UTC) |
---|---|---|
committer | zautrix <zautrix> | 2004-06-26 19:01:18 (UTC) |
commit | b9aad1f15dc600e4dbe4c62d3fcced6363188ba3 (patch) (unidiff) | |
tree | 2c3d4004fb21c72cba65793859f9bcd8ffd3a49c /microkde/kresources/resource.h | |
download | kdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.zip kdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.tar.gz kdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.tar.bz2 |
Initial revision
Diffstat (limited to 'microkde/kresources/resource.h') (more/less context) (ignore whitespace changes)
-rw-r--r-- | microkde/kresources/resource.h | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/microkde/kresources/resource.h b/microkde/kresources/resource.h new file mode 100644 index 0000000..7ff4f23 --- a/dev/null +++ b/microkde/kresources/resource.h | |||
@@ -0,0 +1,401 @@ | |||
1 | /* | ||
2 | This file is part of libkresources | ||
3 | |||
4 | Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org> | ||
5 | Copyright (c) 2002 Jan-Pascal van Best <janpascal@vanbest.org> | ||
6 | |||
7 | This library is free software; you can redistribute it and/or | ||
8 | modify it under the terms of the GNU Library General Public | ||
9 | License as published by the Free Software Foundation; either | ||
10 | version 2 of the License, or (at your option) any later version. | ||
11 | |||
12 | This library is distributed in the hope that it will be useful, | ||
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
15 | Library General Public License for more details. | ||
16 | |||
17 | You should have received a copy of the GNU Library General Public License | ||
18 | along with this library; see the file COPYING.LIB. If not, write to | ||
19 | the Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
20 | Boston, MA 02111-1307, USA. | ||
21 | */ | ||
22 | |||
23 | #ifndef KRESOURCES_RESOURCE_H | ||
24 | #define KRESOURCES_RESOURCE_H | ||
25 | |||
26 | //US | ||
27 | #ifdef QT_THREAD_SUPPORT | ||
28 | #include <qmutex.h> | ||
29 | #endif //QT_THREAD_SUPPORT | ||
30 | |||
31 | #include <qvaluelist.h> | ||
32 | #include <qwidget.h> | ||
33 | |||
34 | #include <qobject.h> | ||
35 | |||
36 | class KConfig; | ||
37 | |||
38 | namespace KRES { | ||
39 | |||
40 | class KLibFactory; | ||
41 | class ConfigWidget; | ||
42 | |||
43 | /** | ||
44 | * @internal | ||
45 | * @libdoc The KDE Resource library | ||
46 | * | ||
47 | * NOTE: this library is NOT (YET?) PUBLIC. Do not publish this | ||
48 | * interface, it is in constant flux. | ||
49 | * | ||
50 | * The KDE Resource framework can be used to manage resources of | ||
51 | * different types, organized in families. The Resource framework | ||
52 | * is currently used for addressbook resources in libkabc and for | ||
53 | * calendar resources in libkcal. | ||
54 | * | ||
55 | * When you want to use the framework for a new family, you need to | ||
56 | * <ul><li>Define a name for your resource family</li> | ||
57 | * <li>subclass Resource and add the fields and method that are needed | ||
58 | * in your application</li> | ||
59 | * <li>If needed, override the doOpen() and doClose() methods. | ||
60 | * <li> Provide a configuration possibility for resources in your | ||
61 | * new family. You can use @ref ResourcesConfigPage to easily create a | ||
62 | * KControl applet</li> | ||
63 | * <li>In your application, you can use @ref ResourceManager to keep track | ||
64 | * of the resources in your family, and you can use @ref ResourceSelectDialog | ||
65 | * to let the user select a single resource.</li> | ||
66 | * </ul> | ||
67 | * | ||
68 | * When you want to add a new resource type to an existing resource family, | ||
69 | * you need to | ||
70 | * <ul><li>Further subclass the family-specific Resource to implement | ||
71 | * resource type-specific operation</li> | ||
72 | * <li>Subclass ResourceConfigWidget to provide a configuration widget | ||
73 | * for your new resource type</li> | ||
74 | * <li>Provide a .desktop file so that the new resource type can be found | ||
75 | * automatically by the ResourceManager</li> | ||
76 | * </ul> | ||
77 | * | ||
78 | * Example: | ||
79 | * | ||
80 | <B>resourceexample.h</B>: | ||
81 | <pre> | ||
82 | #include <kconfig.h> | ||
83 | #include <kresources/resource.h> | ||
84 | |||
85 | class ResourceExample : public KRES::ResourceExample | ||
86 | { | ||
87 | public: | ||
88 | ResourceExample( const KConfig * ); | ||
89 | ~ResourceCalendarExchange(); | ||
90 | void writeConfig( KConfig *config ); | ||
91 | private: | ||
92 | QString mLocation; | ||
93 | QString mPassword; | ||
94 | } | ||
95 | </pre> | ||
96 | <B>resourceexample.cpp</B>: | ||
97 | <pre> | ||
98 | #include <kconfig.h> | ||
99 | |||
100 | #include "resourceexample.h" | ||
101 | |||
102 | ResourceExample::ResourceExample( const KConfig *config ) | ||
103 | : Resource( config ) | ||
104 | { | ||
105 | if ( config ) { | ||
106 | mLocation = config->readEntry( "Location" ); | ||
107 | mPassword = KStringHandler::obscure( config->readEntry( "Password" ) ); | ||
108 | } else { | ||
109 | mLocation = ""; // Or some sensible default | ||
110 | mPassword = ""; | ||
111 | } | ||
112 | } | ||
113 | |||
114 | void ResourceExample::writeConfig( KConfig *config ) | ||
115 | { | ||
116 | KRES::Resource::writeConfig( config ); | ||
117 | config->writeEntry( "Location", mLocation ); | ||
118 | config->writeEntry( "Password", KStringHandler::obscure( mPassword ) ); | ||
119 | } | ||
120 | |||
121 | extern "C" | ||
122 | { | ||
123 | KRES::ResourceExample *config_widget( QWidget *parent ) { | ||
124 | return new ResourceExampleConfig( parent, "Configure Example Resource" ); | ||
125 | } | ||
126 | |||
127 | KRES::Resource *resource( const KConfig *config ) { | ||
128 | return new ResourceExample( config ); | ||
129 | } | ||
130 | } | ||
131 | </pre> | ||
132 | * <B>resourceexampleconfig.h</B>: | ||
133 | <pre> | ||
134 | #include <klineedit.h> | ||
135 | #include <kresources/resourceconfigwidget.h> | ||
136 | |||
137 | #include "resourceexample.h" | ||
138 | |||
139 | class ResourceExampleConfig : public KRES::ResourceConfigWidget | ||
140 | { | ||
141 | Q_OBJECT | ||
142 | |||
143 | public: | ||
144 | ResourceExampleConfig( QWidget* parent = 0, const char* name = 0 ); | ||
145 | |||
146 | public slots: | ||
147 | virtual void loadSettings( KRES::Resource *resource); | ||
148 | virtual void saveSettings( KRES::Resource *resource ); | ||
149 | |||
150 | private: | ||
151 | KLineEdit* mLocationEdit; | ||
152 | KLineEdit* mPasswordEdit; | ||
153 | }; | ||
154 | </pre> | ||
155 | * <B>resourceexampleconfig.cpp</B>: | ||
156 | <pre> | ||
157 | #include <qlayout.h> | ||
158 | #include <qlabel.h" | ||
159 | #include <kresources/resourceconfigwidget.h> | ||
160 | #include "resourceexample.h" | ||
161 | #include "resourceexampleconfig.h" | ||
162 | |||
163 | ResourceExampleConfig::ResourceExampleConfig( QWidget* parent, const char* name ) | ||
164 | : KRES::ResourceConfigWidget( parent, name ) | ||
165 | { | ||
166 | resize( 245, 115 ); | ||
167 | QGridLayout *mainLayout = new QGridLayout( this, 2, 2 ); | ||
168 | |||
169 | QLabel *label = new QLabel( i18n( "Location:" ), this ); | ||
170 | mHostEdit = new KLineEdit( this ); | ||
171 | mainLayout->addWidget( label, 1, 0 ); | ||
172 | mainLayout->addWidget( mHostEdit, 1, 1 ); | ||
173 | |||
174 | label = new QLabel( i18n( "Password:" ), this ); | ||
175 | mPasswordEdit = new KLineEdit( this ); | ||
176 | mPasswordEdit->setEchoMode( QLineEdit::Password ); | ||
177 | mainLayout->addWidget( label, 2, 0 ); | ||
178 | mainLayout->addWidget( mPasswordEdit, 2, 1 ); | ||
179 | } | ||
180 | |||
181 | void ResourceExampleConfig::loadSettings( KRES::Resource *resource ) | ||
182 | { | ||
183 | ResourceExample* res = dynamic_cast<ResourceExample *>( resource ); | ||
184 | if (res) { | ||
185 | mHostEdit->setText( res->host() ); | ||
186 | mPasswordEdit->setText( res->password() ); | ||
187 | } else | ||
188 | kdDebug(5700) << "ERROR: ResourceExampleConfig::loadSettings(): no ResourceExample, cast failed" << endl; | ||
189 | } | ||
190 | |||
191 | void ResourceExampleConfig::saveSettings( KRES::Resource *resource ) | ||
192 | { | ||
193 | ResourceExample* res = dynamic_cast<ResourceExample *>( resource ); | ||
194 | if (res) { | ||
195 | res->setHost(mHostEdit->text()); | ||
196 | res->setPassword(mPasswordEdit->text()); | ||
197 | } else | ||
198 | kdDebug(5700) << "ERROR: ResourceExampleConfig::saveSettings(): no ResourceExample, cast failed" << endl; | ||
199 | } | ||
200 | </pre> | ||
201 | * <B>resourceexample.desktop</B>: | ||
202 | <pre> | ||
203 | [Desktop Entry] | ||
204 | Type=Service | ||
205 | |||
206 | [Misc] | ||
207 | Encoding=UTF-8 | ||
208 | Name=Example Resource | ||
209 | |||
210 | [Plugin] | ||
211 | Type=exchange | ||
212 | X-KDE-Library=resourceexample | ||
213 | </pre> | ||
214 | * <B>Makefile.am</B> | ||
215 | <pre> | ||
216 | kde_module_LTLIBRARIES = resourceexample.la | ||
217 | |||
218 | resourceexample_la_SOURCES = resourceexample.cpp resourceexampleconfig.cpp | ||
219 | resourceexample_la_LDFLAGS= $(all_libraries) -module $(KDE_PLUGIN) | ||
220 | resourceexample_la_LIBADD= -lkderesources | ||
221 | |||
222 | linkdir= $(kde_datadir)/resources/family | ||
223 | link_DATA= resourceexample.desktop | ||
224 | </pre> | ||
225 | * | ||
226 | * | ||
227 | */ | ||
228 | |||
229 | /** | ||
230 | * A @ref Resource is a ... | ||
231 | * | ||
232 | * A subclass should reimplement at least the constructor and the | ||
233 | * @ref writeConfig method. | ||
234 | * | ||
235 | */ | ||
236 | class Resource : public QObject | ||
237 | { | ||
238 | Q_OBJECT | ||
239 | |||
240 | public: | ||
241 | typedef QValueList<Resource *> List; | ||
242 | |||
243 | /** | ||
244 | * Constructor. Construct resource from config. | ||
245 | * @param config Configuration to read persistence information from. | ||
246 | * If config==0, create object using default settings. | ||
247 | */ | ||
248 | Resource( const KConfig* config ); | ||
249 | |||
250 | /** | ||
251 | * Destructor. | ||
252 | */ | ||
253 | virtual ~Resource(); | ||
254 | |||
255 | /** | ||
256 | * Write configuration information for this resource to a configuration | ||
257 | * file. If you override this method, remember to call Resource::writeConfig | ||
258 | * or Terrible Things(TM) will happen. | ||
259 | * @param config Configuration to write persistence information to. | ||
260 | */ | ||
261 | virtual void writeConfig( KConfig* config ); | ||
262 | |||
263 | /** | ||
264 | * Open this resource, if it not already open. Increase the open | ||
265 | * count of this object, and open the resource by calling @ref doOpen(). | ||
266 | * This method may block while another thread is concurrently opening | ||
267 | * or closing the resource. | ||
268 | * | ||
269 | * Returns true if the resource was already opened or if it was opened | ||
270 | * successfully; returns false if the resource was not opened successfully. | ||
271 | */ | ||
272 | bool open(); | ||
273 | |||
274 | /** | ||
275 | * Decrease the open count of this object, and if the count reaches | ||
276 | * zero, close this resource by calling @ref doClose(). | ||
277 | * This method may block while another thread is concurrently closing | ||
278 | * or opening the resource. | ||
279 | */ | ||
280 | void close(); | ||
281 | |||
282 | /** | ||
283 | * Returns whether the resource is open or not. | ||
284 | */ | ||
285 | bool isOpen() const; | ||
286 | |||
287 | /** | ||
288 | * Returns a unique identifier. The identifier is unique for this resource. | ||
289 | * It is created when the resource is first created, and it is retained | ||
290 | * in the resource family configuration file for this resource. | ||
291 | * @return This resource's identifier | ||
292 | */ | ||
293 | QString identifier() const; | ||
294 | |||
295 | /** | ||
296 | * Returns the type of this resource. | ||
297 | */ | ||
298 | QString type() const; | ||
299 | |||
300 | /** | ||
301 | * Mark the resource as read-only. You can override this method, | ||
302 | * but also remember to call Resource::setReadOnly(). | ||
303 | */ | ||
304 | virtual void setReadOnly( bool value ); | ||
305 | |||
306 | /** | ||
307 | * Returns, if the resource is read-only. | ||
308 | */ | ||
309 | virtual bool readOnly() const; | ||
310 | |||
311 | /** | ||
312 | * Set the name of resource.You can override this method, | ||
313 | * but also remember to call Resource::setResourceName(). | ||
314 | */ | ||
315 | virtual void setResourceName( const QString &name ); | ||
316 | |||
317 | /** | ||
318 | * Returns the name of resource. | ||
319 | */ | ||
320 | virtual QString resourceName() const; | ||
321 | |||
322 | /** | ||
323 | Sets, if the resource is active. | ||
324 | */ | ||
325 | void setActive( bool active ); | ||
326 | |||
327 | /** | ||
328 | Return true, if the resource is active. | ||
329 | */ | ||
330 | bool isActive() const; | ||
331 | |||
332 | friend class Factory; | ||
333 | friend class ManagerImpl; | ||
334 | |||
335 | /** | ||
336 | Print resource information as debug output. | ||
337 | */ | ||
338 | virtual void dump() const; | ||
339 | |||
340 | protected: | ||
341 | /** | ||
342 | * Open this resource. When called, the resource must be in | ||
343 | * a closed state. | ||
344 | * | ||
345 | * Returns true if the resource was opened successfully; | ||
346 | * returns false if the resource was not opened successfully. | ||
347 | * | ||
348 | * The result of this call can be accessed later by @ref isOpen() | ||
349 | */ | ||
350 | virtual bool doOpen() { return true; } | ||
351 | |||
352 | /** | ||
353 | * Close this resource. Pre-condition: resource is open. | ||
354 | * Post-condition: resource is closed. | ||
355 | */ | ||
356 | virtual void doClose() {} | ||
357 | |||
358 | void setIdentifier( const QString& identifier ); | ||
359 | void setType( const QString& type ); | ||
360 | |||
361 | private: | ||
362 | class ResourcePrivate; | ||
363 | ResourcePrivate *d; | ||
364 | }; | ||
365 | |||
366 | //US class PluginFactoryBase : public KLibFactory | ||
367 | class PluginFactoryBase | ||
368 | { | ||
369 | public: | ||
370 | virtual Resource *resource( const KConfig *config ) = 0; | ||
371 | |||
372 | virtual ConfigWidget *configWidget( QWidget *parent ) = 0; | ||
373 | |||
374 | protected: | ||
375 | virtual QObject* createObject( QObject*, const char*, const char*, | ||
376 | const QStringList & ) | ||
377 | { | ||
378 | return 0; | ||
379 | } | ||
380 | }; | ||
381 | |||
382 | template<class TR,class TC> | ||
383 | class PluginFactory : public PluginFactoryBase | ||
384 | { | ||
385 | public: | ||
386 | Resource *resource( const KConfig *config ) | ||
387 | { | ||
388 | return new TR( config ); | ||
389 | } | ||
390 | |||
391 | ConfigWidget *configWidget( QWidget *parent ) | ||
392 | { | ||
393 | return new TC( parent ); | ||
394 | } | ||
395 | }; | ||
396 | |||
397 | |||
398 | |||
399 | } | ||
400 | |||
401 | #endif | ||