File indexing completed on 2019-04-16 11:59:10

0001 /*
0002     This file is part of Choqok, the KDE micro-blogging client
0003     Some of below codes are got from Kopete source code.
0004 
0005     Copyright (C) 2008-2012 Mehrdad Momeny <mehrdad.momeny@gmail.com>
0006 
0007     This program is free software; you can redistribute it and/or
0008     modify it under the terms of the GNU General Public License as
0009     published by the Free Software Foundation; either version 2 of
0010     the License or (at your option) version 3 or any later version
0011     accepted by the membership of KDE e.V. (or its successor approved
0012     by the membership of KDE e.V.), which shall act as a proxy
0013     defined in Section 14 of version 3 of the license.
0014 
0015     This program is distributed in the hope that it will be useful,
0016     but WITHOUT ANY WARRANTY; without even the implied warranty of
0017     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
0018     GNU General Public License for more details.
0019 
0020     You should have received a copy of the GNU General Public License
0021     along with this program; if not, see http://www.gnu.org/licenses/
0022 */
0023 
0024 #ifndef CHOQOKPLUGIN_H
0025 #define CHOQOKPLUGIN_H
0026 
0027 #include <QObject>
0028 
0029 #include <KXMLGUIClient>
0030 
0031 #include "choqok_export.h"
0032 
0033 class KPluginInfo;
0034 
0035 /**
0036 * Current Choqok plugin interface version. Interfaces declare plugin version
0037 * to make sure old source (or binary) incompatible plugins are not loaded.
0038 * Increase this if it is necessary that old plugins stop working.
0039 */
0040 #define CHOQOK_PLUGIN_VERSION 1
0041 
0042 namespace Choqok
0043 {
0044 
0045 /**
0046 * @brief Base class for all plugins or microblogs.
0047 *
0048 * To create a plugin, you need to create a .desktop file which looks like that:
0049 * \verbatim
0050 [Desktop Entry]
0051 Encoding=UTF-8
0052 Type=Service
0053 X-Choqok-Version=1
0054 Icon=icon
0055 ServiceTypes=Choqok/Plugin
0056 X-KDE-Library=choqok_myplugin
0057 X-KDE-PluginInfo-Author=Your Name
0058 X-KDE-PluginInfo-Email=your@mail.com
0059 X-KDE-PluginInfo-Name=choqok_myplugin
0060 X-KDE-PluginInfo-Version=0.1
0061 X-KDE-PluginInfo-Website=http://yoursite.com
0062 X-KDE-PluginInfo-Category=Plugins
0063 X-KDE-PluginInfo-Depends=
0064 X-KDE-PluginInfo-License=GPL
0065 X-KDE-PluginInfo-EnabledByDefault=false
0066 Name=MyPlugin
0067 Comment=Plugin that do some nice stuff
0068 \endverbatim
0069 *
0070 * The constructor of your plugin should looks like this:
0071 *
0072 * \code
0073 K_PLUGIN_FACTORY_WITH_JSON( MyPluginFactory, "choqok_plugin.json", registerPlugin < MyPlugin > (); )
0074 
0075 MyPlugin::MyPlugin( QObject *parent, const char *name, const QList\<QVariant\> &  args  )
0076 : Choqok::Plugin( name, parent )
0077 {
0078 //...
0079 }
0080 \endcode
0081 *
0082 * Choqok::Plugin inherits from KXMLGUIClient.  That client is added
0083 * to the Choqok's mainwindow KXMLGUIFactory. So you may add actions
0084 * on the main window.
0085 * Please note that the client is added right after the plugin is created,
0086 * so you have to create every actions in the constructor.
0087 *
0088 * @author Mehrdad Momeny \<mehrdad.momeny@gmail.com\>
0089 */
0090 class CHOQOK_EXPORT Plugin : public QObject, public KXMLGUIClient
0091 {
0092     Q_OBJECT
0093 public:
0094     Plugin(const QString &componentName, QObject *parent);
0095     virtual ~Plugin();
0096 
0097     /**
0098     * Returns the KPluginInfo object associated with this plugin
0099     */
0100     KPluginInfo pluginInfo() const;
0101 
0102     /**
0103     * Get the name of the icon for this plugin. The icon name is taken from the
0104     * .desktop file.
0105     *
0106     * May return an empty string if the .desktop file for this plugin specifies
0107     * no icon name to use.
0108     *
0109     * This is a convenience method that simply calls @ref pluginInfo()->icon().
0110     */
0111     QString pluginIcon() const;
0112 
0113     /**
0114     * Returns the display name of this plugin.
0115     *
0116     * This is a convenience method that simply calls @ref pluginInfo()->name().
0117     */
0118     QString displayName() const;
0119 
0120     /**
0121     * @brief Get the plugin id
0122     * @return the plugin's id which is gotten by calling QObject::metaObject()->className().
0123     */
0124     QString pluginId() const;
0125 
0126     /**
0127     * @brief Returns the pluginName
0128     * This is a convenience method that simply calls @ref pluginInfo()->pluginName().
0129     */
0130     QString pluginName() const;
0131 
0132     /**
0133     * @brief Prepare for unloading a plugin
0134     *
0135     * When unloading a plugin the plugin manager first calls aboutToUnload()
0136     * to indicate the pending unload. Some plugins need time to shutdown
0137     * asynchronously and thus can't be simply deleted in the destructor.
0138     *
0139     * The default implementation immediately emits the @ref readyForUnload() signal,
0140     * which basically makes the shutdown immediate and synchronous. If you need
0141     * more time you can reimplement this method and fire the signal whenever
0142     * you're ready. (you have 3 seconds)
0143     *
0144     * @ref Choqok::MicroBlog reimplement it.
0145     */
0146     virtual void aboutToUnload();
0147 
0148 Q_SIGNALS:
0149     /**
0150     * Notify that the settings of a plugin were changed.
0151     * These changes are passed on from the new KCDialog code in kdelibs/kutils.
0152     */
0153     void settingsChanged();
0154 
0155     /**
0156      * Indicate when we're ready for unload.
0157      * @see aboutToUnload()
0158      */
0159     void readyForUnload();
0160 
0161 private:
0162     class Private;
0163     Private *const d;
0164 };
0165 
0166 }
0167 
0168 #endif // PLUGIN_H