summaryrefslogtreecommitdiffabout
path: root/microkde/kresources/resource.h
Side-by-side diff
Diffstat (limited to 'microkde/kresources/resource.h') (more/less context) (ignore whitespace changes)
-rw-r--r--microkde/kresources/resource.h401
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