File indexing completed on 2024-05-05 04:33:16

 /*
     SPDX-FileCopyrightText: 2004-2018 Gilles Caulier <caulier dot gilles at gmail dot com>
     SPDX-FileCopyrightText: 2004-2005 Renchi Raju <renchi dot raju at gmail dot com>
     SPDX-FileCopyrightText: 2009 Andi Clemens <andi dot clemens at googlemail dot com>
     SPDX-FileCopyrightText: 2009 Aleix Pol Gonzalez <aleixpol at kde dot org>
     SPDX-FileCopyrightText: 2012 Victor Dodon <dodonvictor at gmail dot com>
 
     SPDX-License-Identifier: GPL-2.0-or-later
 */
 
 #ifndef KIPI_PLUGINLOADER_H
 #define KIPI_PLUGINLOADER_H
 
 // Std includes
 
 #include <memory>
 
 // Qt includes
 
 #include <QList>
 
 // KF includes
 
 #include <KService>
 #include <KXmlGuiWindow>
 
 // Local includes
 
 #include "libkipi_export.h"
 
 namespace KIPI
 {
 
 class Plugin;
 class Interface;
 class ConfigWidget;
 
 /**
     \author Gilles Caulier
     \par Maintainer: Victor Dodon
     \class PluginLoader pluginloader.h <KIPI/PluginLoader>
     This is the class that will help host applications to load plugins.
     
     This is a singleton and host applications should create the PluginLoader
     just once, and then use the instance() static method to access it.
 
     The host application must create an instance of the plugin loader, and
     call the method loadPlugins() to get the plugins loaded. To ensure that
     plugins are correctly removed from menus and toolbars when loaded and
     unloaded after constructions, the application must connect to either the
     signals plug() / unplug() or the signal replug(). These signals are
     emitted when a plugin is to be inserted into the menus.
 
     If your application is using KDE XMLGUI, the easiest(nicest) way to get the
     plugins inserted into the menus is by adding an item in your application XML
     ui.rc file looking like this:
 
     \code
 
     <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
     <gui version="1" name="MyKipiApplication" >
 
         <MenuBar>
 
             <Menu name="Image" ><text>&amp;Image</text>
                 <DefineGroup name="kipi_image_group" append="kipi_image_group" />
             </Menu>
 
             <Menu name="Tools"><text>&amp;Tools</text>
                 <DefineGroup name="kipi_album_group" append="kipi_album_group" />
                 <Separator/>
                 <DefineGroup name="kipi_tool_group" append="kipi_tool_group" />
                 <Separator/>
                 <DefineGroup name="kipi_batch_group" append="kipi_batch_group" />
             </Menu>
 
             <Merge/>
 
         </MenuBar>
 
         <ToolBar name="mainToolBar">
             <text>Main Toolbar</text>
         </Toolbar>
 
         <ActionProperties/>
 
     </gui>
 
     \endcode
 
     Then loading plugins into menus could be done with code similar to this implementation:
 
     \code
 
     class MyKipiApplication : public KXmlGuiWindow
     {
         Q_OBJECT
 
     public:
 
         MyKipiApplication();
 
     private Q_SLOTS:
 
         void slotKipiPluginPlug();
 
     private:
 
         KIPI::Interface*    m_iface;
         KIPI::PluginLoader* m_loader;
     };
 
     // -------------------------------------------------------------------------------
 
     MyKipiApplication::MyKipiApplication() : KXmlGuiWindow(0)
     {
         m_iface  = new KIPI::Interface(this, "MyKipiApplication_KIPI_interface");
         m_loader = new KIPI::PluginLoader(this);
         m_loader->setInterface(m_iface);
         m_loader->init();
 
         connect(m_loader, SIGNAL(replug()),
                 this, SLOT(slotKipiPluginPlug()));
 
         m_loader->loadPlugins();
         // Do not delete m_loader as long as any of the plugins are in use
     }
 
     void MyKipiApplication::slotKipiPluginPlug()
     {
         QList<QAction*> kipiImageActions, kipiExportActions, kipiToolsActions;
         PluginLoader::PluginList list = m_loader->pluginList();
 
         // We need to remove loaded plugins from the gui factory
         for (PluginLoader::PluginList::ConstIterator it = list.constBegin(); it != list.constEnd(); ++it )
         {
             Plugin* plugin = (*it)->plugin();
             if ( !plugin || !(*it)->shouldLoad() )
                 continue;
 
             guiFactory()->removeClient(plugin);
         }
 
         for (PluginLoader::PluginList::ConstIterator it = list.constBegin(); it != list.constEnd(); ++it )
         {
             Plugin* plugin = (*it)->plugin();
             if ( !plugin || !(*it)->shouldLoad() )
                 continue;
 
             plugin->setup(this);
         }
 
         // We add plugins to the factory
         for (PluginLoader::PluginList::ConstIterator it = list.constBegin(); it != list.constEnd(); ++it )
         {
             Plugin* plugin = (*it)->plugin();
             if ( !plugin || !(*it)->shouldLoad() )
                 continue;
 
             guiFactory()->addClient(plugin);
         }
     }
 
     \endcode
 
     For a implementation sample used to manage Kipi-plugins in host application,
     look the code of the kxmlkipicmd test application in the "test" folder from libkipi.
 
     To configure which plugins should be loaded, simply call
     PluginLoader::configWidget(), and insert the widget into your normal
     configuration dialog.
 */
 class LIBKIPI_EXPORT PluginLoader : public QObject
 {
     Q_OBJECT
 
 public:
 
     /**
      * \class Info pluginloader.h <KIPI/PluginLoader>
      *
      * Info about a plugin.
      */
     class LIBKIPI_EXPORT Info
     {
 
     public:
 
         Info(KXmlGuiWindow* const parent, const KService::Ptr& service, bool shouldLoad);
         ~Info();
 
         QString       name()             const;
         QString       uname()            const;
         QString       author()           const;
         QString       comment()          const;
         QIcon         icon()             const;
         QString       library()          const;
         KService::Ptr service()          const;
         Plugin*       plugin()           const;
         QStringList   pluginCategories() const;
 
         void reload();
         bool shouldLoad() const;
         void setShouldLoad(bool);
 
     private:
 
         class Private;
         std::unique_ptr<Private> const d;
     };
 
 public:
 
     typedef QList<Info*> PluginList;
 
 public:
 
     /**
      * Use this constructor if your application does not use KDE XML GUI technology.
      * 
      * Note that the PluginLoader is intended to be a singleton, so you
      * should create only one and then use instance().
      */
     PluginLoader();
 
     /**
      * Standard constructor. You must pass the instance of KDE XML GUI application as argument.
      * 
      * Note that the PluginLoader is intended to be a singleton, so you
      * should create only one and then use instance().
      * 
      * @param parent the pointer to the KXmlGuiWindow of your application
      */
     PluginLoader(KXmlGuiWindow* const parent);
 
     /**
      * Standard destructor
      * 
      * Since PluginLoader is a singleton, you should not call this
      * in client code.
      */
     ~PluginLoader() override;
 
     /**
      * Set KIPI interface instance from host application.
      */
     void setInterface(Interface* const interface);
 
     /**
      * Return KIPI host interface instance.
      */
     Interface* interface() const;
 
     /**
      * Set Plugins ignore list, with name of obsoletes plugins to not load through init().
      */
     void setIgnoredPluginsList(const QStringList& ignores);
 
     /**
      * Set disabled plugin actions that will not be plugged into the gui,
      */
     void setDisabledPluginActions(const QStringList& disabledActions);
 
     /**
      * Return the list of disabled plugin actions
      */
     QStringList disabledPluginActions() const;
 
     /**
      * Init plugin loader. Call this method to parse relevant plugins installed on your system.
      * Before to call this method, you must setup KIPI interface instance.
      * Optionally, setup list of plugins to ignore, the constraint list, and
      * the disabled plugin actions
      */
     void init();
 
     /**
      * Call this method to load relevant plugins installed on your system to your KIPI host application
      * @note Plugins can be loaded through Info item.
      */
     void loadPlugins();
 
     /**
      * Returns the list of loaded plugins
      */
     const PluginList& pluginList();
 
     /**
      * Return the kipi-plugins version installed on your computer if it's found through kipiplugins.desktop file.
      */
     QString kipiPluginsVersion() const;
 
     /**
      * Return the config widget with list of plugins to manage.
      */
     ConfigWidget* configWidget(QWidget* const parent) const;
 
     /**
      * Returns plugin loader instance.
      */
     static PluginLoader* instance();
 
 Q_SIGNALS:
 
     void plug(KIPI::PluginLoader::Info*);
     void unplug(KIPI::PluginLoader::Info*);
 
     /// @note Plugin can be plugged through Info item.
     void replug();
 
 private:
 
     class Private;
     std::unique_ptr<Private> const d;
 
 private:
 
     friend class ConfigWidget;
 };
 
 } // namespace KIPI
 
 #endif /* KIPI_PLUGINLOADER_H */