kparts/componentfactory.h

   1 /* This file is part of the KDE project
   2    Copyright (C) 2001 Simon Hausmann <hausmann@kde.org>
   3    Copyright (C) 2002-2006 David Faure <faure@kde.org>
   4
   5    This library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Library General Public
   7    License as published by the Free Software Foundation; either
   8    version 2 of the License, or (at your option) any later version.
   9
  10    This library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU Library General Public License for more details.
  14
  15    You should have received a copy of the GNU Library General Public License
  16    along with this library; see the file COPYING.LIB.  If not, write to the
  17    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18    Boston, MA 02110-1301, USA.
  19 */
  20 #ifndef KPARTS_COMPONENTFACTORY_H
  21 #define KPARTS_COMPONENTFACTORY_H
  22
  23 #include <kparts/factory.h>
  24 #include <kparts/part.h>
  25 #include <kservicetypetrader.h>
  26 #include <klibloader.h>
  27 #include <kmimetypetrader.h>
  28
  29 namespace KParts
  30 {
  31     namespace ComponentFactory
  32     {
  33         /**
  34          * This template function allows to ask the given kparts factory to
  35          * create an instance of the given template type.
  36          *
  37          * Example of usage:
  38          * \code
  39          *     KViewPart *doc = KParts::ComponentFactory::createPartInstanceFromFactory&lt;KViewPart&gt;( factory, parent );
  40          * \endcode
  41          *
  42          * @deprecated use KPluginFactory::create instead
  43          *
  44          * @param factory The factory to ask for the creation of the component
  45          * @param parentWidget the parent widget for the part
  46          * @param parent The parent object (see QObject constructor)
  47          * @param args A list of string arguments, passed to the factory and possibly
  48          *             to the component (see KLibFactory)
  49          * @return A pointer to the newly created object or a null pointer if the
  50          *         factory was unable to create an object of the given type.
  51          */
  52         template <class T>
  53         KDE_DEPRECATED T *createPartInstanceFromFactory( KParts::Factory *factory,
  54                                           QWidget *parentWidget = 0,
  55                                           QObject *parent = 0,
  56                                           const QStringList &args = QStringList() )
  57         {
  58             KParts::Part *object = factory->createPart( parentWidget,
  59                                                         parent,
  60                                                         T::staticMetaObject.className(),
  61                                                         args );
  62
  63             T *result = dynamic_cast<T *>( object );
  64             if ( !result )
  65                 delete object;
  66             return result;
  67         }
  68         /*
  69          * @deprecated use KPluginFactory::create instead
  70          */
  71         template <class T>
  72         KDE_DEPRECATED T *createPartInstanceFromLibrary( const char *libraryName,
  73                                           QWidget *parentWidget = 0,
  74                                           QObject *parent = 0,
  75                                           const QStringList &args = QStringList(),
  76                                           int *error = 0 )
  77         {
  78             KLibrary *library = KLibLoader::self()->library( libraryName );
  79             if ( !library )
  80             {
  81                 if ( error )
  82                     *error = KLibLoader::ErrNoLibrary;
  83                 return 0;
  84             }
  85             KLibFactory *factory = library->factory();
  86             if ( !factory )
  87             {
  88                 library->unload();
  89                 if ( error )
  90                     *error = KLibLoader::ErrNoFactory;
  91                 return 0;
  92             }
  93             KParts::Factory *partFactory = dynamic_cast<KParts::Factory *>( factory );
  94             if ( !partFactory )
  95             {
  96                 library->unload();
  97                 if ( error )
  98                     *error = KLibLoader::ErrNoFactory;
  99                 return 0;
 100             }
 101             T *res = createPartInstanceFromFactory<T>( partFactory, parentWidget,
 102                                                        parent, args );
 103             if ( !res )
 104             {
 105                 library->unload();
 106                 if ( error )
 107                     *error = KLibLoader::ErrNoComponent;
 108             }
 109             return res;
 110         }
 111
 112         /**
 113          * @deprecated use KService::createInstance instead
 114          */
 115         template <class T>
 116         KDE_DEPRECATED T *createPartInstanceFromService( const KService::Ptr &service,
 117                                           QWidget *parentWidget = 0,
 118                                           QObject *parent = 0,
 119                                           const QStringList &args = QStringList(),
 120                                           int *error = 0 )
 121         {
 122             QString library = service->library();
 123             if ( library.isEmpty() )
 124             {
 125                 if ( error )
 126                     *error = KLibLoader::ErrServiceProvidesNoLibrary;
 127                 return 0;
 128             }
 129
 130             return createPartInstanceFromLibrary<T>( library.toLocal8Bit().data(), parentWidget,
 131                                                      parent, args, error );
 132         }
 133
 134         template <class T, class ServiceIterator>
 135         KDE_DEPRECATED T *createPartInstanceFromServices( ServiceIterator begin,
 136                                            ServiceIterator end,
 137                                            QWidget *parentWidget = 0,
 138                                            QObject *parent = 0,
 139                                            const QStringList &args = QStringList(),
 140                                            int *error = 0 )
 141          {
 142             for (; begin != end; ++begin )
 143             {
 144                 KService::Ptr service = *begin;
 145
 146                 if ( error )
 147                     *error = 0;
 148
 149                 T *component = createPartInstanceFromService<T>( service, parentWidget,
 150                                                                  parent, args, error );
 151                 if ( component )
 152                     return component;
 153             }
 154
 155             if ( error )
 156                 *error = KLibLoader::ErrNoServiceFound;
 157
 158             return 0;
 159
 160         }
 161
 162         /**
 163          * This method creates and returns a KParts part from a serviceType (e.g. a mimetype).
 164          *
 165          * You can use this method to create a generic viewer - that can display any
 166          * kind of file, provided that there is a ReadOnlyPart installed for it - in 5 lines:
 167          * \code
 168          * // Given the following: KUrl url, QWidget* parentWidget and QObject* parentObject.
 169          * QString mimetype = KMimeType::findByURL( url )->name();
 170          * KParts::ReadOnlyPart* part = KParts::ComponentFactory::createPartInstanceFromQuery<KParts::ReadOnlyPart>( mimetype, QString(), parentWidget, parentObject );
 171          * if ( part ) {
 172          *     part->openUrl( url );
 173          *     part->widget()->show();  // also insert the widget into a layout, or simply use a KVBox as parentWidget
 174          * }
 175          * \endcode
 176          *
 177          * @deprecated use KMimeTypeTrader::createPartInstanceFromQuery instead
 178          *
 179          * @param mimeType the mimetype which this part is associated with
 180          * @param constraint an optional constraint to pass to the trader (see KTrader)
 181          * @param parentWidget the parent widget, will be set as the parent of the part's widget
 182          * @param parent the parent object for the part itself
 183          * @param args A list of string arguments, passed to the factory and possibly
 184          *             to the component (see KLibFactory)
 185          * @param error The int passed here will receive an error code in case of errors.
 186          *              (See enum KLibLoader::ComponentLoadingError)
 187          * @return A pointer to the newly created object or a null pointer if the
 188          *         factory was unable to create an object of the given type.
 189          */
 190         template <class T>
 191         T *createPartInstanceFromQuery( const QString &mimeType,
 192                                         const QString &constraint,
 193                                         QWidget *parentWidget = 0,
 194                                         QObject *parent = 0,
 195                                         const QStringList &args = QStringList(),
 196                                         int *error = 0 )
 197         {
 198             const KService::List offers = KMimeTypeTrader::self()->query( mimeType, QLatin1String("KParts/ReadOnlyPart"), constraint );
 199             if ( offers.isEmpty() )
 200             {
 201                 if ( error )
 202                     *error = KLibLoader::ErrNoServiceFound;
 203                 return 0;
 204             }
 205
 206             return createPartInstanceFromServices<T>( offers.begin(), offers.end(),
 207                                                       parentWidget,
 208                                                       parent, args, error );
 209         }
 210
 211     }
 212 }
 213
 214 /*
 215  * vim: et sw=4
 216  */
 217
 218 #endif