From ce4a32fe52ef09d8f5ff1dd22c001110902b60a2 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- kparts/componentfactory.h | 401 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 401 insertions(+) create mode 100644 kparts/componentfactory.h (limited to 'kparts/componentfactory.h') diff --git a/kparts/componentfactory.h b/kparts/componentfactory.h new file mode 100644 index 000000000..01616d89f --- /dev/null +++ b/kparts/componentfactory.h @@ -0,0 +1,401 @@ +#ifndef __kparts_componentfactory_h__ +#define __kparts_componentfactory_h__ + +#include +#include +#include +#include + +namespace KParts +{ + + // this is a namespace and not a class because stupid egcs 1.1.2 doesn't grok + // static template methods in classes. !@%@#$! + /** + * Namespace for KParts components + */ + namespace ComponentFactory + { + /** + * This enum type defines the possible error cases that can happen + * when loading a component. + * + *
    + *
  • ErrNoServiceFound - no service implementing the + * given mimetype and fullfilling the given constraint expression + * can be found.
    • + *
  • ErrServiceProvidesNoLibrary - the specified service + * provides no shared library
    • + *
  • ErrNoLibrary - the specified library could not be + * loaded. Use KLibLoader::lastErrorMessage for details.
    • + *
  • ErrNoFactory - the library does not export a factory + * for creating components
    • + *
  • ErrNoComponent - the factory does not support creating + * components of the specified type
    • + *
+ */ + enum ComponentLoadingError { ErrNoServiceFound = 1, + ErrServiceProvidesNoLibrary, + ErrNoLibrary, + ErrNoFactory, + ErrNoComponent }; + + /** + * This template function allows to ask the given factory to create an + * instance of the given template type. + * + * Example of usage: + * \code + * MyPlugin *plugin = KParts::ComponentFactory::createInstanceFromFactory( factory, parent ); + * \endcode + * + * @param factory The factory to ask for the creation of the component + * @param parent The parent object (see QObject constructor) + * @param name The name of the object to create (see QObject constructor) + * @param args A list of string arguments, passed to the factory and possibly + * to the component (see KLibFactory) + * @return A pointer to the newly created object or a null pointer if the + * factory was unable to create an object of the given type. + */ + template + static T *createInstanceFromFactory( KLibFactory *factory, QObject *parent = 0, + const char *name = 0, + const QStringList &args = QStringList() ) + { + QObject *object = factory->create( parent, name, + T::staticMetaObject()->className(), + args ); + + T *result = dynamic_cast( object ); + if ( !result ) + delete object; + return result; + } + + /** + * This template function allows to ask the given kparts factory to create an + * instance of the given template type. + * + * Example of usage: + * \code + * KViewPart *doc = KParts::ComponentFactory::createPartInstanceFromFactory( factory, parent ); + * \endcode + * + * @param factory The factory to ask for the creation of the component + * @param parentWidget the parent widget for the part + * @param widgetName the name of the part's widget + * @param parent The parent object (see QObject constructor) + * @param name The name of the object to create (see QObject constructor) + * @param args A list of string arguments, passed to the factory and possibly + * to the component (see KLibFactory) + * @return A pointer to the newly created object or a null pointer if the + * factory was unable to create an object of the given type. + */ + template + static T *createPartInstanceFromFactory( KParts::Factory *factory, + QWidget *parentWidget = 0, + const char *widgetName = 0, + QObject *parent = 0, + const char *name = 0, + const QStringList &args = QStringList() ) + { + KParts::Part *object = factory->createPart( parentWidget, widgetName, + parent, name, + T::staticMetaObject()->className(), + args ); + + T *result = dynamic_cast( object ); + if ( !result ) + delete object; + return result; + } + + /** + * This template allows to load the specified library and ask the + * factory to create an instance of the given template type. + * + * @param libraryName The library to open + * @param parent The parent object (see QObject constructor) + * @param name The name of the object to create (see QObject constructor) + * @param args A list of string arguments, passed to the factory and possibly + * to the component (see KLibFactory) + * @param error + * @return A pointer to the newly created object or a null pointer if the + * factory was unable to create an object of the given type. + */ + template + static T *createInstanceFromLibrary( const char *libraryName, QObject *parent = 0, + const char *name = 0, + const QStringList &args = QStringList(), + int *error = 0 ) + { + KLibrary *library = KLibLoader::self()->library( libraryName ); + if ( !library ) + { + if ( error ) + *error = ErrNoLibrary; + return 0; + } + KLibFactory *factory = library->factory(); + if ( !factory ) + { + library->unload(); + if ( error ) + *error = ErrNoFactory; + return 0; + } + T *res = createInstanceFromFactory( factory, parent, name, args ); + if ( !res ) + { + library->unload(); + if ( error ) + *error = ErrNoComponent; + } + return res; + } + + template + static T *createPartInstanceFromLibrary( const char *libraryName, + QWidget *parentWidget = 0, + const char *widgetName = 0, + QObject *parent = 0, + const char *name = 0, + const QStringList &args = QStringList(), + int *error = 0 ) + { + KLibrary *library = KLibLoader::self()->library( libraryName ); + if ( !library ) + { + if ( error ) + *error = ErrNoLibrary; + return 0; + } + KLibFactory *factory = library->factory(); + if ( !factory ) + { + library->unload(); + if ( error ) + *error = ErrNoFactory; + return 0; + } + KParts::Factory *partFactory = dynamic_cast( factory ); + if ( !partFactory ) + { + library->unload(); + if ( error ) + *error = ErrNoFactory; + return 0; + } + T *res = createPartInstanceFromFactory( partFactory, parentWidget, + widgetName, parent, name, args ); + if ( !res ) + { + library->unload(); + if ( error ) + *error = ErrNoComponent; + } + return res; + } + + template + static T *createInstanceFromService( const KService::Ptr &service, + QObject *parent = 0, + const char *name = 0, + const QStringList &args = QStringList(), + int *error = 0 ) + { + QString library = service->library(); + if ( library.isEmpty() ) + { + if ( error ) + *error = ErrServiceProvidesNoLibrary; + return 0; + } + + return createInstanceFromLibrary( library.local8Bit().data(), parent, + name, args, error ); + } + + template + static T *createPartInstanceFromService( const KService::Ptr &service, + QWidget *parentWidget = 0, + const char *widgetName = 0, + QObject *parent = 0, + const char *name = 0, + const QStringList &args = QStringList(), + int *error = 0 ) + { + QString library = service->library(); + if ( library.isEmpty() ) + { + if ( error ) + *error = ErrServiceProvidesNoLibrary; + return 0; + } + + return createPartInstanceFromLibrary( library.local8Bit().data(), parentWidget, + widgetName, parent, name, args, error ); + } + + template + static T *createInstanceFromServices( ServiceIterator begin, ServiceIterator end, + QObject *parent = 0, + const char *name = 0, + const QStringList &args = QStringList(), + int *error = 0 ) + { + for (; begin != end; ++begin ) + { + KService::Ptr service = *begin; + + if ( error ) + *error = 0; + + T *component = createInstanceFromService( service, parent, name, + args, error ); + if ( component ) + return component; + } + + if ( error ) + *error = ErrNoServiceFound; + + return 0; + + } + + template + static T *createPartInstanceFromServices( ServiceIterator begin, + ServiceIterator end, + QWidget *parentWidget = 0, + const char *widgetName = 0, + QObject *parent = 0, + const char *name = 0, + const QStringList &args = QStringList(), + int *error = 0 ) + { + for (; begin != end; ++begin ) + { + KService::Ptr service = *begin; + + if ( error ) + *error = 0; + + T *component = createPartInstanceFromService( service, parentWidget, + widgetName, parent, + name, args, error ); + if ( component ) + return component; + } + + if ( error ) + *error = ErrNoServiceFound; + + return 0; + + } + + /** + * This method creates and returns a plugin, from the trader query for a given serviceType. + * + * Example: + * \code + * KMyAppPlugin* plugin = KParts::ComponentFactory::createInstanceFromQuery( serviceType, QString::null, parentObject ); + * if ( plugin ) { + * .... + * } + * \endcode + * + * @param serviceType the type of service for which to find a plugin + * @param constraint an optional constraint to pass to the trader (see KIO::KTrader) + * @param parent the parent object for the part itself + * @param name the name that will be given to the part + * @param args A list of string arguments, passed to the factory and possibly + * to the component (see KLibFactory) + * @param error The int passed here will receive an error code in case of errors. + * (See enum #ComponentLoadingError) + * @return A pointer to the newly created object or a null pointer if the + * factory was unable to create an object of the given type. + */ + template + static T *createInstanceFromQuery( const QString &serviceType, + const QString &constraint = QString::null, + QObject *parent = 0, + const char *name = 0, + const QStringList &args = QStringList(), + int *error = 0 ) + { + KTrader::OfferList offers = KTrader::self()->query( serviceType, constraint ); + if ( offers.isEmpty() ) + { + if ( error ) + *error = ErrNoServiceFound; + return 0; + } + + return createInstanceFromServices( offers.begin(), + offers.end(), + parent, name, args, error ); + } + + /** + * This method creates and returns a KParts part from a serviceType (e.g. a mimetype). + * + * You can use this method to create a generic viewer - that can display any + * kind of file, provided that there is a ReadOnlyPart installed for it - in 5 lines: + * \code + * // Given the following: KURL url, QWidget* parentWidget and QObject* parentObject. + * QString mimetype = KMimeType::findByURL( url )->name(); + * KParts::ReadOnlyPart* part = KParts::ComponentFactory::createPartInstanceFromQuery( mimetype, QString::null, parentWidget, 0, parentObject, 0 ); + * if ( part ) { + * part->openURL( url ); + * part->widget()->show(); // also insert the widget into a layout, or simply use a QVBox as parentWidget + * } + * \endcode + * + * @param serviceType the type of service for which to find a part, e.g. a mimetype + * @param constraint an optional constraint to pass to the trader (see KTrader) + * @param parentWidget the parent widget, will be set as the parent of the part's widget + * @param widgetName the name that will be given to the part's widget + * @param parent the parent object for the part itself + * @param name the name that will be given to the part + * @param args A list of string arguments, passed to the factory and possibly + * to the component (see KLibFactory) + * @param error The int passed here will receive an error code in case of errors. + * (See enum #ComponentLoadingError) + * @return A pointer to the newly created object or a null pointer if the + * factory was unable to create an object of the given type. + */ + template + static T *createPartInstanceFromQuery( const QString &serviceType, + const QString &constraint, + QWidget *parentWidget = 0, + const char *widgetName = 0, + QObject *parent = 0, + const char *name = 0, + const QStringList &args = QStringList(), + int *error = 0 ) + { + KTrader::OfferList offers = KTrader::self()->query( serviceType, QString::fromLatin1("KParts/ReadOnlyPart"), constraint, QString::null ); + if ( offers.isEmpty() ) + { + if ( error ) + *error = ErrNoServiceFound; + return 0; + } + + return createPartInstanceFromServices( offers.begin(), offers.end(), + parentWidget, widgetName, + parent, name, args, error ); + } + + } + +} + +/* + * vim: et sw=4 + */ + +#endif + -- cgit v1.2.1