messageviewer/pluginloader.h

   1 /*  -*- c++ -*-
   2     This file is part of libkdepim.
   3
   4     Copyright (c) 2002,2004 Marc Mutz <mutz@kde.org>
   5
   6     This library is free software; you can redistribute it and/or
   7     modify it under the terms of the GNU Library General Public
   8     License as published by the Free Software Foundation; either
   9     version 2 of the License, or (at your option) any later version.
  10
  11     This library is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14     Library General Public License for more details.
  15
  16     You should have received a copy of the GNU Library General Public License
  17     along with this library; see the file COPYING.LIB.  If not, write to
  18     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19     Boston, MA 02110-1301, USA.
  20 */
  21
  22 #ifndef PLUGINLOADER_H
  23 #define PLUGINLOADER_H
  24
  25 #include "pluginloaderbase.h"
  26 #include <KLibrary>
  27
  28 /**
  29  * @short A generic plugin loader for when KPart::Plugin is overkill
  30  * @author Marc Mutz <mutz@kde.org> based on KABC's FormatFactory
  31  *
  32  * This is a generic plugin loader / factory for small plugins that
  33  * don't want to be QObjects.
  34  *
  35  * @section Usage
  36  *
  37  * A PluginLoader takes two template arguments, <code>T</code> and
  38  * <code>T_config</code>:
  39  *
  40  * <dl>
  41  * <dt>T</dt><dd>The type of object to return</dd>
  42  * <dt>T_config::mainfunc</dt><dd>The suffix of the factory function to call
  43  *          in the library to obtain a new object of type <code>T</code>.
  44  *          The string passed to <code>KLibrary::symbol()</code> is
  45  *          <code>libName_mainfunc</code>.</dd>
  46  * <dt>T_config::path</dt><dd>The search pattern for <tt>.desktop</tt> files
  47  *          containing the plugin descriptions. This is the string passed as
  48  *          the @p filter argument to
  49  *          <code>KStandardDirs::findAllResources</code>.</dd>
  50  * </dl>
  51  *
  52  * The last two parameters being strings, they are passed via an
  53  * encapsulating class, of which <code>mainfunc</code> and
  54  * <code>path</code> are public static members:
  55  *
  56  * <pre>
  57  * struct MyObjectPluginLoaderConfig {
  58  *   static const char * const mainfunc;
  59  *   static const char * const path;
  60  * };
  61  * const char * const MyObjectPluginLoaderConfig::mainfunc = "myapp_create_myobject";
  62  * const char * const MyObjectPluginLoaderConfig::path = "myapp/plugins/ *.desktop";
  63  * </pre>
  64  *
  65  * You would then use a <tt>typedef</tt> to create a less unwieldy
  66  * name for your plugin loader:
  67  *
  68  * <pre>
  69  * typedef PluginLoader< MyObject, MyObjectPluginLoaderConfig > MyObjectPluginLoader;
  70  * </pre>
  71  *
  72  * All of this is what the
  73  * <code>DEFINE_PLUGIN_LOADER(pluginloadername,type,mainfunc,path)</code> macro
  74  * achieves.
  75  *
  76  **/
  77 template< typename T, typename T_config >
  78 class PluginLoader : public PluginLoaderBase {
  79 protected:
  80   PluginLoader() : PluginLoaderBase() {}
  81
  82 private:
  83   static PluginLoader<T,T_config> * mSelf;
  84
  85 public:
  86   virtual ~PluginLoader() { mSelf = 0; }
  87
  88   /** Returns the single instance of this loader. */
  89   static PluginLoader<T,T_config> * instance() {
  90     if ( !mSelf ) {
  91       mSelf = new PluginLoader<T,T_config>();
  92       mSelf->scan();
  93     }
  94     return mSelf;
  95   }
  96
  97   /** Rescans the plugin directory to find any newly installed
  98       plugins.
  99   **/
 100   virtual void scan() {
 101     doScan( T_config::path );
 102   }
 103
 104   /** Returns a pointer to a plugin object (of type @p T) or a null
 105       pointer if the type wasn't found. You can extend this method
 106       for when you want to handle builtin types */
 107   virtual T * createForName( const QString & type ) const {
 108     KLibrary::void_function_ptr main_func = mainFunc( type, T_config::mainfunc );
 109     if ( !main_func ) return 0;
 110
 111     // cast to a pointer to a function returning T*, call it and
 112     // return the result; don't you love C? ;-)
 113     return ((T* (*)())( main_func ))();
 114   }
 115 };
 116
 117 template< typename T, typename T_config >
 118 PluginLoader<T,T_config> * PluginLoader<T,T_config>::mSelf = 0;
 119
 120 #define DEFINE_PLUGIN_LOADER( pl, t, mf, p ) \
 121   namespace { /* don't pollute namespaces */ \
 122     struct KDE_EXPORT pl##Config { \
 123       static const char * const mainfunc; \
 124       static const char * const path; \
 125     }; \
 126     const char * const pl##Config::mainfunc = mf; \
 127     const char * const pl##Config::path = p; \
 128   } \
 129   typedef PluginLoader< t, pl##Config > pl; \
 130
 131
 132 #endif // PLUGINLOADER_H