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

 /*
     SPDX-FileCopyrightText: 2004-2018 Gilles Caulier <caulier dot gilles at gmail dot com>
     SPDX-FileCopyrightText: 2012 Victor Dodon <dodonvictor at gmail dot com>
     SPDX-FileCopyrightText: 2004-2005 Renchi Raju <renchi dot raju at gmail dot com>
     SPDX-FileCopyrightText: 2004-2005 Jesper K. Pedersen <blackie at kde dot org>
     SPDX-FileCopyrightText: 2004-2005 Aurelien Gateau <aurelien dot gateau at free dot fr>
 
     SPDX-License-Identifier: GPL-2.0-or-later
 */
 
 #ifndef KIPI_PLUGIN_H
 #define KIPI_PLUGIN_H
 
 // Std includes
 
 #include <memory>
 
 // Qt includes
 
 #include <QObject>
 #include <QList>
 #include <QHash>
 #include <QDomElement>
 #include <QDomNode>
 #include <QDomDocument>
 
 // KF includes
 
 #include <KXMLGUIClient>
 
 // Local includes
 
 #include "libkipi_export.h"
 
 class QAction;
 
 namespace KIPI
 {
 
 class Interface;
 
 /**
  * The Category enum.
  */
 enum Category
 {
     InvalidCategory = -1,
     ImagesPlugin    = 0,
     ToolsPlugin,
     ImportPlugin,
     ExportPlugin,
     BatchPlugin,
     CollectionsPlugin
 };
 
 /**
  * @class Plugin plugin.h <KIPI/Plugin>
  *
  * @short Base class for the KIPI plugins
  *
  */
 class LIBKIPI_EXPORT Plugin : public QObject, public KXMLGUIClient
 {
     Q_OBJECT
 
     typedef QList<QDomElement>                        QDomElemList;
     typedef QHash<QString, QDomElemList>              QHashPath;
     typedef QMap<QWidget*, QMap<QAction*, Category> > ActionCategoryMap;
 
 public:
 
     /**
      * Constructs a plugin
      *
      * @param parent the parent of this object
      * @param name the name of the plugin
      */
     Plugin(QObject* const parent, const char* name);
 
     /**
      * Standard destructor
      *
      * All the actions in the actionCollection are deleted before the plugin is
      * deleted.
      */
     ~Plugin() override;
 
     /**
      * Returns the plugin actions associated with passed @p widget, or with
      * the default widget, if @p widget is a nullptr. The actions are in
      * the same order as added to the plugin.
      */
     QList<QAction*> actions(QWidget* const widget = nullptr) const;
 
     /**
      * Returns the KIPI::Interface
      */
     Interface* interface() const;
 
     /**
      * Virtual method that must be overridden by the non abstract descendants and
      * must be called before any actions are added.
      *
      * @param widget The widget which holds the plugin. It will be set as the default widget.
      */
     virtual void setup(QWidget* const widget) = 0;
 
     /**
      * Returns the category of the specified plugin action, or InvalidCategory
      * if the action is not recognised
      */
     Category category(QAction* const action) const;
 
     /**
      * Force the plugin to reread and to reload its XML file
      */
     void rebuild();
 
 protected:
 
     /**
      * Register an action to the plugin instance and add it to the action collection.
      *
      * The action is added only if the action name is not in the disabled actions
      * list of the PluginLoader singleton class.
      *
      * @param name the name by which the action will be added to the action collection
      * @param action the action to add
      *
      * @note It just calls addAction(const QString&, QAction* const, Category)
      * with the default category, so the default
      * category must be set using setDefaultCategory() before you use this method
      */
     void addAction(const QString& name, QAction* const action);
 
     /**
      * Register action to the plugin instance and add it to the action collection
      *
      * The action is added only if the action name is not in the disabled actions
      * list of the PluginLoader singleton class.
      *
      * @param name the name by which the action will be added to the action collection
      * @param action the action to add
      * @param cat the category of the action
      */
     void addAction(const QString& name, QAction* const action, Category cat);
 
     /**
      * Sets the default category of the plugin actions
      *
      * \sa defaultCategory()
      */
     void setDefaultCategory(Category cat);
 
     /**
      * Returns the default category of the plugin actions
      *
      * \sa setDefaultCategory()
      */
     Category defaultCategory() const;
 
     /**
      * Sets the name of the XML file associated with this KXMLGUIClient. You must
      * provide only the filename without slashes.
      *
      * The default XML file must be installed in the dir ${KDE_INSTALL_KXMLGUIDIR}/kipi,
      * modifications will be stored in the local config dir.
      *
      * \sa uiBaseName()
      */
     void setUiBaseName(const char* name);
 
     /**
      * Return the base name of the XML file associated with this KXMLGUIClient
      *
      * \sa setUiBaseName()
      */
     QString uiBaseName() const;
 
     /**
      * Adapt the XML file of the plugin with the one of the KXmlGuiWindow main window.
      * It's recommended to call it on every creation of the plugin.
      *
      * @note the XML file of the plugin must be set using setUiBaseName()
      */
     void setupXML();
 
 private:
 
     /** For internal uses only
       */
     void addAction(QAction* const action);
     void addAction(QAction* const action, Category cat);
 
     void mergeXMLFile(KXMLGUIClient* const host);
     void clearActions();
 
 private:
 
     class Private;
     std::unique_ptr<Private> const d;
 };
 
 } // namespace KIPI
 
 #endif  // KIPI_PLUGIN_H