2
This file is part of libkresources
4
Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org>
5
Copyright (c) 2002 Jan-Pascal van Best <janpascal@vanbest.org>
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.
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.
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.
22
#ifndef KRESOURCES_RESOURCE_H
23
#define KRESOURCES_RESOURCE_H
26
#include <qvaluelist.h>
29
#include <klibloader.h>
38
\mainpage The KDE Resource library
40
The KDE Resource framework can be used to manage resources of
41
different types, organized in families. The Resource framework
42
is for example used for addressbook resources in libkabc and for
43
calendar resources in libkcal.
45
When you want to use the framework for a new family, you need to
46
<ul><li>Define a name for your resource family</li>
47
<li>subclass Resource and add the fields and method that are needed
48
in your application</li>
49
<li>If needed, override the doOpen() and doClose() methods.
50
<li>In your application, you can use ResourceManager to keep track
51
of the resources in your family, and you can use ResourceSelectDialog
52
to let the user select a single resource.</li>
55
When you want to add a new resource type to an existing resource family,
57
<ul><li>Further subclass the family-specific Resource to implement
58
resource type-specific operation</li>
59
<li>Subclass ResourceConfigWidget to provide a configuration widget
60
for your new resource type</li>
61
<li>Provide a .desktop file so that the new resource type can be found
62
automatically by the ResourceManager</li>
67
<B>resourceexample.h</B>:
70
#include <kresources/resource.h>
72
class ResourceExample : public KRES::Resource
75
ResourceExample( const KConfig * );
77
void writeConfig( KConfig *config );
85
<B>resourceexample.cpp</B>:
89
#include "resourceexample.h"
91
ResourceExample::ResourceExample( const KConfig *config )
95
mLocation = config->readPathEntry( "Location" );
96
mPassword = KStringHandler::obscure( config->readEntry( "Password" ) );
98
mLocation = ""; // Or some sensible default
103
void ResourceExample::writeConfig( KConfig *config )
105
KRES::Resource::writeConfig( config );
106
config->writePathEntry( "Location", mLocation );
107
config->writeEntry( "Password", KStringHandler::obscure( mPassword ) );
112
KRES::ResourceExample *config_widget( QWidget *parent ) {
113
return new ResourceExampleConfig( parent, "Configure Example Resource" );
116
KRES::Resource *resource( const KConfig *config ) {
117
return new ResourceExample( config );
122
<B>resourceexampleconfig.h</B>:
124
#include <klineedit.h>
125
#include <kresources/resourceconfigwidget.h>
127
#include "resourceexample.h"
129
class ResourceExampleConfig : public KRES::ResourceConfigWidget
133
ResourceExampleConfig( QWidget *parent = 0, const char *name = 0 );
136
virtual void loadSettings( KRES::Resource *resource);
137
virtual void saveSettings( KRES::Resource *resource );
140
KLineEdit *mLocationEdit;
141
KLineEdit *mPasswordEdit;
145
<B>resourceexampleconfig.cpp</B>:
149
#include <kresources/resourceconfigwidget.h>
150
#include "resourceexample.h"
151
#include "resourceexampleconfig.h"
153
ResourceExampleConfig::ResourceExampleConfig( QWidget *parent, const char *name )
154
: KRES::ResourceConfigWidget( parent, name )
156
QGridLayout *mainLayout = new QGridLayout( this, 2, 2 );
158
QLabel *label = new QLabel( i18n( "Location:" ), this );
159
mHostEdit = new KLineEdit( this );
160
mainLayout->addWidget( label, 1, 0 );
161
mainLayout->addWidget( mHostEdit, 1, 1 );
163
label = new QLabel( i18n( "Password:" ), this );
164
mPasswordEdit = new KLineEdit( this );
165
mPasswordEdit->setEchoMode( QLineEdit::Password );
166
mainLayout->addWidget( label, 2, 0 );
167
mainLayout->addWidget( mPasswordEdit, 2, 1 );
170
void ResourceExampleConfig::loadSettings( KRES::Resource *resource )
172
ResourceExample *res = dynamic_cast<ResourceExample *>( resource );
174
mHostEdit->setText( res->host() );
175
mPasswordEdit->setText( res->password() );
177
kdDebug() << "ERROR: ResourceExampleConfig::loadSettings(): no ResourceExample, cast failed" << endl;
180
void ResourceExampleConfig::saveSettings( KRES::Resource *resource )
182
ResourceExample *res = dynamic_cast<ResourceExample *>( resource );
184
res->setHost( mHostEdit->text() );
185
res->setPassword( mPasswordEdit->text() );
187
kdDebug() << "ERROR: ResourceExampleConfig::saveSettings(): no ResourceExample, cast failed" << endl;
191
<B>resourceexample.desktop</B>:
198
Name=Example Resource
202
X-KDE-Library=resourceexample
207
kde_module_LTLIBRARIES = resourceexample.la
209
resourceexample_la_SOURCES = resourceexample.cpp resourceexampleconfig.cpp
210
resourceexample_la_LDFLAGS = $(all_libraries) -module $(KDE_PLUGIN)
211
resourceexample_la_LIBADD = -lkresources
213
servicedir = $(kde_datadir)/resources/example
214
service_DATA = resourceexample.desktop
220
This class provides a resource which is managed in a general way.
222
A Resource represents the concept of an object with the following attributes:
224
- Applications operate on sets of one or more Resource objects.
225
- Creation and deletetion of Resource objects is done in a general way,
226
independent of concrete functionality of the Resource.
227
- The end user has control over creation, deletion and configuration of
229
- Properties, behaviour and configuration of different Resource objects can
231
- Resources can be active or inactive.
232
- There is one special Resource which is the standard Resource. This can for
233
example be used as default destination for newly created object managed
234
by a certain Resource family.
235
- Activation of Resources can be covered by a two step process of being opened
236
and then loaded. Deactivation corresponds to saving and closing.
237
- Different application ususally share the same set of Resources.
239
The Resource base class provides the management functionality. Classes
240
inheriting from Resource automatically appear in the general kresources
243
Concrete functionality of Resources is specified per family by a subclass of
244
Resource. This classes in turn have subclasses which implement the different
245
flavours of the functionality represented by the family.
247
A subclass should reimplement at least the constructor and the
250
An example for a Resource subclass hierarchy would be the "calendar" family.
251
The ResourceCalendar subclass would specify an API for accessing calendar
252
data. Subclasses of ResourceCalendar would implement this API for local files,
253
remote files, specific calendar servers etc.
255
class Resource : public QObject
257
friend class Factory;
258
friend class ManagerImpl;
262
typedef QValueList<Resource *> List;
265
* Constructor. Construct resource from config.
266
* @param config Configuration to read persistence information from.
267
* If config is 0, create object using default settings.
269
Resource( const KConfig *config );
277
* Write configuration information for this resource to a configuration
278
* file. If you override this method, remember to call Resource::writeConfig
279
* or Terrible Things(TM) will happen.
280
* @param config Configuration to write persistence information to.
282
virtual void writeConfig( KConfig *config );
285
* Open this resource, if it not already open. Increase the open
286
* count of this object, and open the resource by calling doOpen().
287
* This method may block while another thread is concurrently opening
288
* or closing the resource.
290
* Returns true if the resource was already opened or if it was opened
291
* successfully; returns false if the resource was not opened successfully.
296
* Decrease the open count of this object, and if the count reaches
297
* zero, close this resource by calling doClose().
298
* This method may block while another thread is concurrently closing
299
* or opening the resource.
304
* Returns whether the resource is open or not.
309
* Returns a unique identifier. The identifier is unique for this resource.
310
* It is created when the resource is first created, and it is retained
311
* in the resource family configuration file for this resource.
312
* @return This resource's identifier
314
QString identifier() const;
317
* Returns the type of this resource.
319
QString type() const;
322
* Mark the resource as read-only. You can override this method,
323
* but also remember to call Resource::setReadOnly().
325
virtual void setReadOnly( bool value );
328
* Returns, if the resource is read-only.
330
virtual bool readOnly() const;
333
* Set the name of resource. You can override this method,
334
* but also remember to call Resource::setResourceName().
336
virtual void setResourceName( const QString &name );
339
* Returns the name of resource.
341
virtual QString resourceName() const;
344
Sets, if the resource is active.
346
void setActive( bool active );
349
Return true, if the resource is active.
351
bool isActive() const;
354
Print resource information as debug output.
356
virtual void dump() const;
360
* Open this resource. When called, the resource must be in
363
* Returns true if the resource was opened successfully;
364
* returns false if the resource was not opened successfully.
366
* The result of this call can be accessed later by isOpen()
368
virtual bool doOpen() { return true; }
371
* Close this resource. Pre-condition: resource is open.
372
* Post-condition: resource is closed.
374
virtual void doClose() {}
376
void setIdentifier( const QString &identifier );
377
void setType( const QString &type );
380
class ResourcePrivate;
384
class PluginFactoryBase : public KLibFactory
387
virtual Resource *resource( const KConfig *config ) = 0;
389
virtual ConfigWidget *configWidget( QWidget *parent ) = 0;
392
virtual QObject* createObject( QObject *, const char *, const char *,
393
const QStringList & )
399
template<class TR,class TC>
400
class PluginFactory : public PluginFactoryBase
403
Resource *resource( const KConfig *config )
405
return new TR( config );
408
ConfigWidget *configWidget( QWidget *parent )
410
return new TC( parent );
added
removed
extra/kde330/xresource.h
