File indexing completed on 2022-10-04 17:30:21

0001 // SPDX-License-Identifier: GPL-2.0-or-later
0002 // SPDX-FileCopyrightText: 2001 Dominik Seichter <domseichter@web.de>
0003 
0004 #ifndef PLUGIN_H
0005 #define PLUGIN_H
0006 
0007 #include <QPixmap>
0008 #include <QString>
0009 
0010 #include <KConfigGroup>
0011 #include <KSharedConfig>
0012 
0013 class BatchRenamer;
0014 class KConfigGroup;
0015 class PluginLoader;
0016 
0017 /** An enum to determine the correct plugin type.
0018  *
0019  *  A plugin may be of different types at a time.
0020  */
0021 enum EPluginType {
0022     ePluginType_Token     = 0x01, ///< A plugin that handles a token in brackets [ ]
0023     ePluginType_Filename  = 0x02, ///< A plugin that transforms the complete final filename
0024     ePluginType_File      = 0x04  ///< A plugin that changes the finally renamed file
0025 };
0026 
0027 /** This is the abstract interface that has to be implemented
0028  *  by all KRename plugins.
0029  */
0030 class Plugin
0031 {
0032 public:
0033     explicit Plugin(PluginLoader *loader);
0034     virtual ~Plugin();
0035 
0036     /**
0037      * Creates a help entry for the QStringList returned by help,
0038      * adds correct separator and brackets where necessary.
0039      *
0040      * \param token the token ([ brackets ] will be added to surround it)
0041      * \help help for the token
0042      *
0043      * \see help()
0044      */
0045     static QString createHelpEntry(const QString &token, const QString &help);
0046 
0047     /**
0048      * @returns a name of the plugin that can be displayed
0049      *          to the user. This name should be internationalized.
0050      */
0051     virtual const QString name() const = 0;
0052 
0053     /**
0054      * Determines the type of the plugin.
0055      * Different enum values may be or'ed together.
0056      *
0057      * @returns the type of the plugin.
0058      */
0059     virtual int type() const = 0;
0060 
0061     /**
0062      * @returns an icon for this plugin.
0063      */
0064     virtual const QIcon icon() const = 0;
0065 
0066     /** Set the enabled state of a plugin
0067      *  so that it can be used.
0068      *
0069      *  \param b the enabled state of the plugin.
0070      */
0071     inline void setEnabled(bool b);
0072 
0073     /**
0074      * @returns true if this plugin is enabled.
0075      * Only use it if it is enabled.
0076      */
0077     inline bool isEnabled() const;
0078 
0079     /**
0080      * @returns true if this plugins is always enabled
0081      *
0082      * Warning: If you return true here, the user has no possibility to
0083      *          disable this plugin.
0084      */
0085     virtual bool enabledByDefault() const = 0;
0086 
0087     /**
0088      * This function is the core of your plugin.
0089      *
0090      * It does the actual processing of a file, filename or token depending of the type
0091      * of your plugin.
0092      *
0093      * \see type()
0094      *
0095      * @param b the parent BatchRenamer instance calling this plugin
0096      * @param index the index of the current file (i.e. the first file has index 0,
0097      *              the second file to be renamed has index 1 ....)
0098      * @param filenameOrToken this parameter depends on the type of your plugin.
0099      *                        If type is ePluginType_File, this is the absolute path
0100      *                        or URL to the renamed file.
0101      *                        If type is ePluginType_Filename, this is the filename
0102      *                        (without path) as created by KRename.
0103      *                        If type is ePluginType_Token, this is the contents of a token
0104      *                        in brackets. If your plugin supports the token [example],
0105      *                        KRename will pass the strign "example" to your method.
0106      * @param eCurrentType the current type of plugin that is requested (for plugins that support more than one type)
0107      *
0108      * @returns the result of the function, depending on type().
0109      * @returns an empty QString if this plugin has nothing to do.
0110      * @returns A new filename if type is ePluginType_Filename
0111      * @returns the value of the token if type is ePluginType_Token
0112      * @returns an error message or an empty QString if type is ePluginType_File
0113      */
0114     virtual QString processFile(BatchRenamer *b, int index, const QString &filenameOrToken, EPluginType eCurrentType) = 0;
0115 
0116     /** Get a list of all tokens supported by this plugin.
0117      *
0118      *  If the token type != ePluginType_Token you have to return an empty list
0119      *
0120      *  @returns a list of all supported tokens. The returned strings will be treated
0121      *           as regular expressions to find a plugin which supports a token.
0122      */
0123     virtual const QStringList &supportedTokens() const = 0;
0124 
0125     /** Returns help descriptions for the supported tokens
0126      *
0127      *  The returned stringlist contains strings that are the tokens
0128      *  and the description separated by ;;
0129      *
0130      *  @returns a stringlist containing help on the supported tokens
0131      */
0132     virtual const QStringList &help() const = 0;
0133 
0134     /** Create a user interface for this plugin
0135      *
0136      *  @param parent the parent widget of this plugin
0137      */
0138     virtual void createUI(QWidget *parent) const = 0;
0139 
0140     /** Load the plugin configuration.
0141      *
0142      *  Called when plugins should load their configuration.
0143      *
0144      *  @param group config group where the configuration should be read from
0145      */
0146     virtual void loadConfig(KConfigGroup &group);
0147 
0148     /** Save the plugin configuration.
0149      *
0150      *  Called when plugins should save their configuration.
0151      *
0152      *  @param group config group where the configuration should be stored
0153      */
0154     virtual void saveConfig(KConfigGroup &group) const;
0155 
0156     /*
0157         virtual bool checkError() = 0;
0158         virtual void drawInterface( QWidget* w, QVBoxLayout* l ) = 0;
0159         virtual void fillStructure() { }
0160         virtual QString processFile( BatchRenamer* b, int i, QString token, int mode ) = 0;
0161         virtual void finished() { }
0162 
0163         virtual void addHelp( HelpDialogData* data );
0164         virtual void removeHelp(  HelpDialogData* data );
0165 
0166         virtual void clearCache();
0167 
0168         virtual const QPixmap getIcon() const;
0169         virtual const QStringList getKeys() const;
0170     */
0171 
0172 protected:
0173     PluginLoader *m_pluginLoader;
0174 
0175 private:
0176     bool m_enabled;
0177 };
0178 
0179 inline void Plugin::setEnabled(bool b)
0180 {
0181     m_enabled = b;
0182 }
0183 
0184 inline bool Plugin::isEnabled() const
0185 {
0186     return this->enabledByDefault() || m_enabled;
0187 }
0188 
0189 #endif // PLUGIN_H