File indexing completed on 2022-11-29 20:25:16

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