home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kresources / resource.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-01-15  |  12.0 KB  |  421 lines
  1. /*
  2.     This file is part of libkresources
  3.  
  4.     Copyright (c) 2001-2003 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., 51 Franklin Street, Fifth Floor,
  20.     Boston, MA 02110-1301, USA.
  21. */
  22. #ifndef KRESOURCES_RESOURCE_H
  23. #define KRESOURCES_RESOURCE_H
  24.  
  25. #include <qmutex.h>
  26. #include <qvaluelist.h>
  27. #include <qwidget.h>
  28.  
  29. #include <klibloader.h>
  30.  
  31. class KConfig;
  32.  
  33. namespace KRES {
  34.  
  35. class ConfigWidget;
  36.  
  37. /**
  38.   \mainpage The KDE Resource library
  39.  
  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.
  44.  
  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>
  53.   </ul>
  54.  
  55.   When you want to add a new resource type to an existing resource family,
  56.   you need to
  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>
  63.   </ul>
  64.  
  65.   Example:
  66.  
  67.   <B>resourceexample.h</B>:
  68. \code
  69. #include <kconfig.h>
  70. #include <kresources/resource.h>
  71.  
  72. class ResourceExample : public KRES::Resource
  73. {
  74.   public:
  75.     ResourceExample( const KConfig * );
  76.     ~ResourceExample();
  77.     void writeConfig( KConfig *config );
  78.  
  79.   private:
  80.     QString mLocation;
  81.     QString mPassword;
  82. }
  83. \endcode
  84.  
  85.   <B>resourceexample.cpp</B>:
  86. \code
  87. #include <kconfig.h>
  88.  
  89. #include "resourceexample.h"
  90.  
  91. ResourceExample::ResourceExample( const KConfig *config )
  92.     : Resource( config )
  93. {
  94.   if ( config ) {
  95.     mLocation = config->readPathEntry( "Location" );
  96.     mPassword = KStringHandler::obscure( config->readEntry( "Password" ) );
  97.   } else {
  98.     mLocation = ""; // Or some sensible default
  99.     mPassword = "";
  100.   }
  101. }
  102.  
  103. void ResourceExample::writeConfig( KConfig *config )
  104. {
  105.   KRES::Resource::writeConfig( config );
  106.   config->writePathEntry( "Location", mLocation );
  107.   config->writeEntry( "Password", KStringHandler::obscure( mPassword ) );
  108. }
  109.  
  110. extern "C"
  111. {
  112.   KRES::ResourceExample *config_widget( QWidget *parent ) {
  113.     return new ResourceExampleConfig( parent, "Configure Example Resource" );
  114.   }
  115.  
  116.   KRES::Resource *resource( const KConfig *config ) {
  117.     return new ResourceExample( config );
  118.   }
  119. }
  120. \endcode
  121.  
  122.   <B>resourceexampleconfig.h</B>:
  123. \code
  124. #include <klineedit.h>
  125. #include <kresources/resourceconfigwidget.h>
  126.  
  127. #include "resourceexample.h"
  128.  
  129. class ResourceExampleConfig : public KRES::ResourceConfigWidget
  130. {
  131.     Q_OBJECT
  132.   public:
  133.     ResourceExampleConfig( QWidget *parent = 0, const char *name = 0 );
  134.  
  135.   public slots:
  136.     virtual void loadSettings( KRES::Resource *resource);
  137.     virtual void saveSettings( KRES::Resource *resource );
  138.  
  139.   private:
  140.     KLineEdit *mLocationEdit;
  141.     KLineEdit *mPasswordEdit;
  142. };
  143. \endcode
  144.  
  145.   <B>resourceexampleconfig.cpp</B>:
  146. \code
  147. #include <qlayout.h>
  148. #include <qlabel.h>
  149. #include <kresources/resourceconfigwidget.h>
  150. #include "resourceexample.h"
  151. #include "resourceexampleconfig.h"
  152.  
  153. ResourceExampleConfig::ResourceExampleConfig( QWidget *parent,  const char *name )
  154.   : KRES::ResourceConfigWidget( parent, name )
  155. {
  156.   QGridLayout *mainLayout = new QGridLayout( this, 2, 2 );
  157.  
  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 );
  162.  
  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 );
  168. }
  169.  
  170. void ResourceExampleConfig::loadSettings( KRES::Resource *resource )
  171. {
  172.   ResourceExample *res = dynamic_cast<ResourceExample *>( resource );
  173.   if ( res ) {
  174.     mHostEdit->setText( res->host() );
  175.     mPasswordEdit->setText( res->password() );
  176.   } else
  177.     kdDebug() << "ERROR: ResourceExampleConfig::loadSettings(): no ResourceExample, cast failed" << endl;
  178. }
  179.  
  180. void ResourceExampleConfig::saveSettings( KRES::Resource *resource )
  181. {
  182.   ResourceExample *res = dynamic_cast<ResourceExample *>( resource );
  183.   if ( res ) {
  184.     res->setHost( mHostEdit->text() );
  185.     res->setPassword( mPasswordEdit->text() );
  186.   } else
  187.     kdDebug() << "ERROR: ResourceExampleConfig::saveSettings(): no ResourceExample, cast failed" << endl;
  188. }
  189. \endcode
  190.  
  191.   <B>resourceexample.desktop</B>:
  192. \code
  193. [Desktop Entry]
  194. Type=Service
  195.  
  196. [Misc]
  197. Encoding=UTF-8
  198. Name=Example Resource
  199.  
  200. [Plugin]
  201. Type=exchange
  202. X-KDE-Library=resourceexample
  203. \endcode
  204.  
  205.   <B>Makefile.am</B>
  206. \code
  207. kde_module_LTLIBRARIES = resourceexample.la
  208.  
  209. resourceexample_la_SOURCES = resourceexample.cpp resourceexampleconfig.cpp
  210. resourceexample_la_LDFLAGS = $(all_libraries) -module $(KDE_PLUGIN)
  211. resourceexample_la_LIBADD = -lkresources
  212.  
  213. servicedir = $(kde_datadir)/resources/example
  214. service_DATA = resourceexample.desktop
  215. \endcode
  216.  
  217. */
  218.  
  219. /**
  220.   This class provides a resource which is managed in a general way.
  221.   
  222.   A Resource represents the concept of an object with the following attributes:
  223.  
  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
  228.     Resource object.
  229.   - Properties, behaviour and configuration of different Resource objects can
  230.     widely differ.
  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.
  238.  
  239.   The Resource base class provides the management functionality. Classes
  240.   inheriting from Resource automatically appear in the general kresources
  241.   kcontrol module.
  242.  
  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.
  246.  
  247.   A subclass should reimplement at least the constructor and the
  248.   writeConfig method.
  249.  
  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.
  254. */
  255. class KRESOURCES_EXPORT Resource : public QObject
  256. {
  257.     friend class Factory;
  258.     friend class ManagerImpl;
  259.  
  260.     Q_OBJECT
  261.   public:
  262.     typedef QValueList<Resource *> List;
  263.  
  264.     /**
  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.
  268.      */
  269.     Resource( const KConfig *config );
  270.  
  271.     /**
  272.      * Destructor.
  273.      */
  274.     virtual ~Resource();
  275.  
  276.     /**
  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.
  281.      */
  282.     virtual void writeConfig( KConfig *config );
  283.  
  284.     /**
  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.
  289.      *
  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.
  292.      */
  293.     bool open();
  294.  
  295.     /**
  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.
  300.      */
  301.     void close();
  302.  
  303.     /**
  304.      * Returns whether the resource is open or not.
  305.      */
  306.     bool isOpen() const;
  307.  
  308.     /**
  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
  313.      */
  314.     QString identifier() const;
  315.  
  316.     /**
  317.      * Returns the type of this resource.
  318.      */
  319.     QString type() const;
  320.  
  321.     /**
  322.      * Mark the resource as read-only. You can override this method,
  323.      * but also remember to call Resource::setReadOnly().
  324.      */
  325.     virtual void setReadOnly( bool value );
  326.  
  327.     /**
  328.      * Returns, if the resource is read-only.
  329.      */
  330.     virtual bool readOnly() const;
  331.  
  332.     /**
  333.      * Set the name of resource. You can override this method,
  334.      * but also remember to call Resource::setResourceName().
  335.      */
  336.     virtual void setResourceName( const QString &name );
  337.  
  338.     /**
  339.      * Returns the name of resource.
  340.      */
  341.     virtual QString resourceName() const;
  342.  
  343.     /**
  344.       Sets, if the resource is active.
  345.     */
  346.     void setActive( bool active );
  347.  
  348.     /**
  349.       Return true, if the resource is active.
  350.     */
  351.     bool isActive() const;
  352.  
  353.     /**
  354.       Print resource information as debug output.
  355.     */
  356.     virtual void dump() const;
  357.  
  358.   protected:
  359.     /**
  360.      * Open this resource. When called, the resource must be in
  361.      * a closed state.
  362.      *
  363.      * Returns true if the resource was opened successfully;
  364.      * returns false if the resource was not opened successfully.
  365.      *
  366.      * The result of this call can be accessed later by isOpen()
  367.      */
  368.     virtual bool doOpen() { return true; }
  369.  
  370.     /**
  371.      * Close this resource. Pre-condition: resource is open.
  372.      * Post-condition: resource is closed.
  373.      */
  374.     virtual void doClose() {}
  375.  
  376.     void setIdentifier( const QString &identifier );
  377.     void setType( const QString &type );
  378.  
  379.   private:
  380.     class ResourcePrivate;
  381.     ResourcePrivate *d;
  382. };
  383.  
  384. class KRESOURCES_EXPORT PluginFactoryBase : public KLibFactory
  385. {
  386.   public:
  387.     virtual Resource *resource( const KConfig *config ) = 0;
  388.  
  389.     virtual ConfigWidget *configWidget( QWidget *parent ) = 0;
  390.  
  391.   protected:
  392.     virtual QObject* createObject( QObject *parent, const char *name, const char *className,
  393.                                    const QStringList & args)
  394.     {
  395.       Q_UNUSED(parent);
  396.       Q_UNUSED(name);
  397.       Q_UNUSED(className);
  398.       Q_UNUSED(args);
  399.       return 0;
  400.     }
  401. };
  402.  
  403. template<class TR,class TC>
  404. class PluginFactory : public PluginFactoryBase
  405. {
  406.   public:
  407.     Resource *resource( const KConfig *config )
  408.     {
  409.       return new TR( config );
  410.     }
  411.  
  412.     ConfigWidget *configWidget( QWidget *parent )
  413.     {
  414.       return new TC( parent );
  415.     }
  416. };
  417.  
  418. }
  419.  
  420. #endif
  421.