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 @@ +/* + This file is part of libkresources + + Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org> + Copyright (c) 2002 Jan-Pascal van Best <janpascal@vanbest.org> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. +*/ + +#ifndef KRESOURCES_RESOURCE_H +#define KRESOURCES_RESOURCE_H + +//US +#ifdef QT_THREAD_SUPPORT +#include <qmutex.h> +#endif //QT_THREAD_SUPPORT + +#include <qvaluelist.h> +#include <qwidget.h> + +#include <qobject.h> + +class KConfig; + +namespace KRES { + +class KLibFactory; +class ConfigWidget; + +/** + * @internal + * @libdoc The KDE Resource library + * + * NOTE: this library is NOT (YET?) PUBLIC. Do not publish this + * interface, it is in constant flux. + * + * The KDE Resource framework can be used to manage resources of + * different types, organized in families. The Resource framework + * is currently used for addressbook resources in libkabc and for + * calendar resources in libkcal. + * + * When you want to use the framework for a new family, you need to + * <ul><li>Define a name for your resource family</li> + * <li>subclass Resource and add the fields and method that are needed + * in your application</li> + * <li>If needed, override the doOpen() and doClose() methods. + * <li> Provide a configuration possibility for resources in your + * new family. You can use @ref ResourcesConfigPage to easily create a + * KControl applet</li> + * <li>In your application, you can use @ref ResourceManager to keep track + * of the resources in your family, and you can use @ref ResourceSelectDialog + * to let the user select a single resource.</li> + * </ul> + * + * When you want to add a new resource type to an existing resource family, + * you need to + * <ul><li>Further subclass the family-specific Resource to implement + * resource type-specific operation</li> + * <li>Subclass ResourceConfigWidget to provide a configuration widget + * for your new resource type</li> + * <li>Provide a .desktop file so that the new resource type can be found + * automatically by the ResourceManager</li> + * </ul> + * + * Example: + * +<B>resourceexample.h</B>: +<pre> +#include <kconfig.h> +#include <kresources/resource.h> + +class ResourceExample : public KRES::ResourceExample +{ +public: + ResourceExample( const KConfig * ); + ~ResourceCalendarExchange(); + void writeConfig( KConfig *config ); +private: + QString mLocation; + QString mPassword; +} +</pre> +<B>resourceexample.cpp</B>: +<pre> +#include <kconfig.h> + +#include "resourceexample.h" + +ResourceExample::ResourceExample( const KConfig *config ) + : Resource( config ) +{ + if ( config ) { + mLocation = config->readEntry( "Location" ); + mPassword = KStringHandler::obscure( config->readEntry( "Password" ) ); + } else { + mLocation = ""; // Or some sensible default + mPassword = ""; + } +} + +void ResourceExample::writeConfig( KConfig *config ) +{ + KRES::Resource::writeConfig( config ); + config->writeEntry( "Location", mLocation ); + config->writeEntry( "Password", KStringHandler::obscure( mPassword ) ); +} + +extern "C" +{ + KRES::ResourceExample *config_widget( QWidget *parent ) { + return new ResourceExampleConfig( parent, "Configure Example Resource" ); + } + + KRES::Resource *resource( const KConfig *config ) { + return new ResourceExample( config ); + } +} +</pre> +* <B>resourceexampleconfig.h</B>: +<pre> +#include <klineedit.h> +#include <kresources/resourceconfigwidget.h> + +#include "resourceexample.h" + +class ResourceExampleConfig : public KRES::ResourceConfigWidget +{ + Q_OBJECT + +public: + ResourceExampleConfig( QWidget* parent = 0, const char* name = 0 ); + +public slots: + virtual void loadSettings( KRES::Resource *resource); + virtual void saveSettings( KRES::Resource *resource ); + +private: + KLineEdit* mLocationEdit; + KLineEdit* mPasswordEdit; +}; +</pre> +* <B>resourceexampleconfig.cpp</B>: +<pre> +#include <qlayout.h> +#include <qlabel.h" +#include <kresources/resourceconfigwidget.h> +#include "resourceexample.h" +#include "resourceexampleconfig.h" + +ResourceExampleConfig::ResourceExampleConfig( QWidget* parent, const char* name ) + : KRES::ResourceConfigWidget( parent, name ) +{ + resize( 245, 115 ); + QGridLayout *mainLayout = new QGridLayout( this, 2, 2 ); + + QLabel *label = new QLabel( i18n( "Location:" ), this ); + mHostEdit = new KLineEdit( this ); + mainLayout->addWidget( label, 1, 0 ); + mainLayout->addWidget( mHostEdit, 1, 1 ); + + label = new QLabel( i18n( "Password:" ), this ); + mPasswordEdit = new KLineEdit( this ); + mPasswordEdit->setEchoMode( QLineEdit::Password ); + mainLayout->addWidget( label, 2, 0 ); + mainLayout->addWidget( mPasswordEdit, 2, 1 ); +} + +void ResourceExampleConfig::loadSettings( KRES::Resource *resource ) +{ + ResourceExample* res = dynamic_cast<ResourceExample *>( resource ); + if (res) { + mHostEdit->setText( res->host() ); + mPasswordEdit->setText( res->password() ); + } else + kdDebug(5700) << "ERROR: ResourceExampleConfig::loadSettings(): no ResourceExample, cast failed" << endl; +} + +void ResourceExampleConfig::saveSettings( KRES::Resource *resource ) +{ + ResourceExample* res = dynamic_cast<ResourceExample *>( resource ); + if (res) { + res->setHost(mHostEdit->text()); + res->setPassword(mPasswordEdit->text()); + } else + kdDebug(5700) << "ERROR: ResourceExampleConfig::saveSettings(): no ResourceExample, cast failed" << endl; +} +</pre> +* <B>resourceexample.desktop</B>: +<pre> +[Desktop Entry] +Type=Service + +[Misc] +Encoding=UTF-8 +Name=Example Resource + +[Plugin] +Type=exchange +X-KDE-Library=resourceexample +</pre> +* <B>Makefile.am</B> +<pre> +kde_module_LTLIBRARIES = resourceexample.la + +resourceexample_la_SOURCES = resourceexample.cpp resourceexampleconfig.cpp +resourceexample_la_LDFLAGS= $(all_libraries) -module $(KDE_PLUGIN) +resourceexample_la_LIBADD= -lkderesources + +linkdir= $(kde_datadir)/resources/family +link_DATA= resourceexample.desktop +</pre> + * + * + */ + +/** + * A @ref Resource is a ... + * + * A subclass should reimplement at least the constructor and the + * @ref writeConfig method. + * + */ +class Resource : public QObject +{ + Q_OBJECT + + public: + typedef QValueList<Resource *> List; + + /** + * Constructor. Construct resource from config. + * @param config Configuration to read persistence information from. + * If config==0, create object using default settings. + */ + Resource( const KConfig* config ); + + /** + * Destructor. + */ + virtual ~Resource(); + + /** + * Write configuration information for this resource to a configuration + * file. If you override this method, remember to call Resource::writeConfig + * or Terrible Things(TM) will happen. + * @param config Configuration to write persistence information to. + */ + virtual void writeConfig( KConfig* config ); + + /** + * Open this resource, if it not already open. Increase the open + * count of this object, and open the resource by calling @ref doOpen(). + * This method may block while another thread is concurrently opening + * or closing the resource. + * + * Returns true if the resource was already opened or if it was opened + * successfully; returns false if the resource was not opened successfully. + */ + bool open(); + + /** + * Decrease the open count of this object, and if the count reaches + * zero, close this resource by calling @ref doClose(). + * This method may block while another thread is concurrently closing + * or opening the resource. + */ + void close(); + + /** + * Returns whether the resource is open or not. + */ + bool isOpen() const; + + /** + * Returns a unique identifier. The identifier is unique for this resource. + * It is created when the resource is first created, and it is retained + * in the resource family configuration file for this resource. + * @return This resource's identifier + */ + QString identifier() const; + + /** + * Returns the type of this resource. + */ + QString type() const; + + /** + * Mark the resource as read-only. You can override this method, + * but also remember to call Resource::setReadOnly(). + */ + virtual void setReadOnly( bool value ); + + /** + * Returns, if the resource is read-only. + */ + virtual bool readOnly() const; + + /** + * Set the name of resource.You can override this method, + * but also remember to call Resource::setResourceName(). + */ + virtual void setResourceName( const QString &name ); + + /** + * Returns the name of resource. + */ + virtual QString resourceName() const; + + /** + Sets, if the resource is active. + */ + void setActive( bool active ); + + /** + Return true, if the resource is active. + */ + bool isActive() const; + + friend class Factory; + friend class ManagerImpl; + + /** + Print resource information as debug output. + */ + virtual void dump() const; + + protected: + /** + * Open this resource. When called, the resource must be in + * a closed state. + * + * Returns true if the resource was opened successfully; + * returns false if the resource was not opened successfully. + * + * The result of this call can be accessed later by @ref isOpen() + */ + virtual bool doOpen() { return true; } + + /** + * Close this resource. Pre-condition: resource is open. + * Post-condition: resource is closed. + */ + virtual void doClose() {} + + void setIdentifier( const QString& identifier ); + void setType( const QString& type ); + + private: + class ResourcePrivate; + ResourcePrivate *d; +}; + +//US class PluginFactoryBase : public KLibFactory +class PluginFactoryBase +{ + public: + virtual Resource *resource( const KConfig *config ) = 0; + + virtual ConfigWidget *configWidget( QWidget *parent ) = 0; + + protected: + virtual QObject* createObject( QObject*, const char*, const char*, + const QStringList & ) + { + return 0; + } +}; + +template<class TR,class TC> +class PluginFactory : public PluginFactoryBase +{ + public: + Resource *resource( const KConfig *config ) + { + return new TR( config ); + } + + ConfigWidget *configWidget( QWidget *parent ) + { + return new TC( parent ); + } +}; + + + +} + +#endif |