File indexing completed on 2024-06-16 04:33:42

0001 /*
0002     SPDX-FileCopyrightText: 2004-2009 Sebastian Trueg <trueg@k3b.org>
0003     SPDX-FileCopyrightText: 1998-2009 Sebastian Trueg <trueg@k3b.org>
0004 
0005     SPDX-License-Identifier: GPL-2.0-or-later
0006 */
0007 
0008 #ifndef _K3B_PROJECT_PLUGIN_H_
0009 #define _K3B_PROJECT_PLUGIN_H_
0010 
0011 #include "k3bdoc.h"
0012 #include "k3bplugin.h"
0013 
0014 #include <KConfigGroup>
0015 #include <QFlags>
0016 #include <QIcon>
0017 
0018 #include "k3b_export.h"
0019 
0020 class KConfigGroup;
0021 
0022 namespace K3b {
0023 
0024     /**
0025      * In case your plugin provides a GUI it is recommended to use the
0026      * ProjectPluginGUIBase interface. That way K3b can embed the GUI into
0027      * a fancy dialog which fits the overall look.
0028      *
0029      * This is not derived from QWidget to make it possible to inherit
0030      * from other QWidget derivates.
0031      */
0032     class ProjectPluginGUIBase
0033     {
0034     public:
0035         ProjectPluginGUIBase() {}
0036         virtual ~ProjectPluginGUIBase() {}
0037 
0038         virtual QWidget* qWidget() = 0;
0039 
0040         /**
0041          * Title used for the GUI
0042          */
0043         virtual QString title() const = 0;
0044         virtual QString subTitle() const { return QString(); }
0045 
0046         /**
0047          * Used to read settings and defaults.
0048          */
0049         virtual void readSettings( const KConfigGroup& ) {}
0050         virtual void saveSettings( KConfigGroup ) {}
0051 
0052         /**
0053          * Start the plugin. This method should do the actual work.
0054          */
0055         virtual void activate() = 0;
0056     };
0057 
0058 
0059     /**
0060      * A ProjectPlugin is supposed to modify a k3b project in some way or
0061      * create additional data based on the project.
0062      *
0063      * Reimplement createGUI or activate and use setText, setToolTip, setWhatsThis, and setIcon
0064      * to specify the gui elements used when presenting the plugin to the user.
0065      */
0066     class LIBK3B_EXPORT ProjectPlugin : public Plugin
0067     {
0068         Q_OBJECT
0069 
0070     public:
0071         Q_DECLARE_FLAGS( Type, Doc::Type )
0072         
0073         /**
0074          * @param type The type of the plugin which can be a combination of @see Doc::Type
0075          * @param gui If true the plugin is supposed to provide a widget via @p createGUI(). In that case
0076          *            @p activate() will not be used. A plugin has a GUI if it's functionality is started
0077          *            by some user input.
0078          */
0079         explicit ProjectPlugin( Type type, bool gui = false, QObject* parent = 0 );
0080 
0081         ~ProjectPlugin() override {
0082         }
0083 
0084         // TODO: maybe we should use something like "ProjectPlugin/AudioCD" based on the type?
0085         QString category() const override { return "ProjectPlugin"; }
0086 
0087         QString categoryName() const override;
0088 
0089         /**
0090          * audio, data, videocd, or videodvd
0091          * Needs to return a proper type. The default implementation returns the type specified
0092          * in the constructor.
0093          */
0094         virtual Type type() const { return m_type; }
0095 
0096         /**
0097          * Text used for menu entries and the like.
0098          */
0099         QString text() const { return m_text; }
0100         QString toolTip() const { return m_toolTip; }
0101         QString whatsThis() const { return m_whatsThis; }
0102         QIcon icon() const { return m_icon; }
0103 
0104         bool hasGUI() const { return m_hasGUI; }
0105 
0106         /**
0107          * Create the GUI which provides the features for the plugin.
0108          * This only needs to be implemented in case hasGUI returns true.
0109          * The returned object has to be a QWidget based class.
0110          *
0111          * @param doc based on the type returned by the factory
0112          *            this will be the doc to work on. It should
0113          *            be dynamically casted to the needed project type.
0114          */
0115         virtual ProjectPluginGUIBase* createGUI( Doc* doc, QWidget* = 0 ) { Q_UNUSED(doc); return 0; }
0116 
0117         /**
0118          * This is where the action happens.
0119          * There is no need to implement this in case hasGUI returns true.
0120          *
0121          * @param doc based on the type returned by the factory
0122          *            this will be the doc to work on. It should
0123          *            be dynamically casted to the needed project type.
0124          *
0125          * @param parent the parent widget to be used for things like progress dialogs.
0126          */
0127         virtual void activate( Doc* doc, QWidget* parent ) { Q_UNUSED(doc); Q_UNUSED(parent); }
0128 
0129     protected:
0130         void setText( const QString& s ) { m_text = s; }
0131         void setToolTip( const QString& s ) { m_toolTip = s; }
0132         void setWhatsThis( const QString& s ) { m_whatsThis = s; }
0133         void setIcon( const QIcon& i ) { m_icon = i; }
0134 
0135     private:
0136         Type m_type;
0137         bool m_hasGUI;
0138         QString m_text;
0139         QString m_toolTip;
0140         QString m_whatsThis;
0141         QIcon m_icon;
0142     };
0143 }
0144 
0145 Q_DECLARE_OPERATORS_FOR_FLAGS( K3b::ProjectPlugin::Type )
0146 
0147 #endif