File indexing completed on 2019-04-16 17:04:21

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