kopete/libkopete/kopeteplugin.h

   1 /*
   2     kopeteplugin.h - Kopete Plugin API
   3
   4     Copyright (c) 2001-2002 by Duncan Mac-Vicar Prett <duncan@kde.org>
   5     Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
   6     Copyright (c) 2002-2005 by Olivier Goffart        <ogoffart@kde.org>
   7
   8     Copyright (c) 2002-2003 by the Kopete developers  <kopete-devel@kde.org>
   9
  10     *************************************************************************
  11     *                                                                       *
  12     * This library is free software; you can redistribute it and/or         *
  13     * modify it under the terms of the GNU Lesser General Public            *
  14     * License as published by the Free Software Foundation; either          *
  15     * version 2 of the License, or (at your option) any later version.      *
  16     *                                                                       *
  17     *************************************************************************
  18 */
  19
  20 #ifndef KOPETEPLUGIN_H
  21 #define KOPETEPLUGIN_H
  22
  23 #include <kxmlguiclient.h>
  24 #include <QtCore/QObject>
  25 #include <kdemacros.h>
  26
  27 #include "kopete_export.h"
  28
  29 class KPluginInfo;
  30
  31 namespace Kopete
  32 {
  33
  34 class MetaContact;
  35
  36 /**
  37  * @brief Base class for all plugins or protocols.
  38  *
  39  * To create a plugin, you need to create a .desktop file which looks like that:
  40  * \verbatim
  41 [Desktop Entry]
  42 Encoding=UTF-8
  43 Type=Service
  44 X-Kopete-Version=1000900
  45 Icon=icon
  46 ServiceTypes=Kopete/Plugin
  47 X-KDE-Library=kopete_myplugin
  48 X-KDE-PluginInfo-Author=Your Name
  49 X-KDE-PluginInfo-Email=your@mail.com
  50 X-KDE-PluginInfo-Name=kopete_myplugin
  51 X-KDE-PluginInfo-Version=0.0.1
  52 X-KDE-PluginInfo-Website=http://yoursite.com
  53 X-KDE-PluginInfo-Category=Plugins
  54 X-KDE-PluginInfo-Depends=
  55 X-KDE-PluginInfo-License=GPL
  56 X-KDE-PluginInfo-EnabledByDefault=false
  57 Name=MyPlugin
  58 Comment=Plugin that do some nice stuff
  59  \endverbatim
  60  *
  61  * The constructor of your plugin should looks like this:
  62  *
  63  * \code
  64         typedef KGenericFactory<MyPlugin> MyPluginFactory;
  65         static const KAboutData aboutdata("kopete_myplugin", 0, ki18n("MyPlugin") , "1.0" );
  66         K_EXPORT_COMPONENT_FACTORY( kopete_myplugin, MyPluginFactory( &aboutdata )  )
  67
  68         MyPlugin::MyPlugin( QObject *parent, const char *name, const QStringList &  args  )
  69                 : Kopete::Plugin( MyPluginFactory::componentData(), parent, name )
  70         {
  71                 //...
  72         }
  73  \endcode
  74  *
  75  * Kopete::Plugin inherits from KXMLGUIClient.  That client is added
  76  * to the Kopete's mainwindow KXMLGUIFactory. So you may add actions
  77  * on the main window (for hinstance in the meta contact popup menu).
  78  * Please note the the client is added right after the plugin is created.
  79  * so you have to create every actions in the constructor
  80  *
  81  * @author Duncan Mac-Vicar P. <duncan@kde.org>
  82  * @author Olivier Goffart <ogoffart\@kde.org>
  83  */
  84 class KOPETE_EXPORT Plugin : public QObject, public KXMLGUIClient
  85 {
  86         Q_OBJECT
  87
  88 public:
  89         Plugin( const KComponentData &instance, QObject *parent );
  90         virtual ~Plugin();
  91
  92         /**
  93          * Returns the KPluginInfo object associated with this plugin
  94          */
  95         KPluginInfo pluginInfo() const;
  96
  97         /**
  98          * Get the name of the icon for this plugin. The icon name is taken from the
  99          * .desktop file.
 100          *
 101          * May return an empty string if the .desktop file for this plugin specifies
 102          * no icon name to use.
 103          *
 104          * This is a convenience method that simply calls @ref pluginInfo()->icon().
 105          */
 106         QString pluginIcon() const;
 107
 108         /**
 109          * Returns the display name of this plugin.
 110          *
 111          * This is a convenience method that simply calls @ref pluginInfo()->name().
 112          */
 113         QString displayName() const;
 114
 115         /**
 116          * @brief Get the plugin id
 117          * @return the plugin's id which is gotten by calling QObject::metaObject()->className().
 118          */
 119         QString pluginId() const;
 120
 121         /**
 122          * Return the list of all keys from the address book in which the plugin
 123          * is interested. Those keys are monitored for changes upon load and
 124          * during runtime. When the key actually changes, the plugin's
 125          * addressBookKeyChanged( Kopete::MetaContact *mc, const QString &key )
 126          * is called.
 127          * You can add fields to the list using @ref addAddressBookField()
 128          */
 129         QStringList addressBookFields() const;
 130
 131         /**
 132          * Return the index field as set by @ref addAddressBookField()
 133          */
 134         QString addressBookIndexField() const;
 135
 136         /**
 137          * Mode for an address book field as used by @ref addAddressBookField()
 138          */
 139         enum AddressBookFieldAddMode { AddOnly, MakeIndexField };
 140
 141         /**
 142          * Add a field to the list of address book fields. See also @ref addressBookFields()
 143          * for a description of the fields.
 144          *
 145          * Set mode to MakeIndexField to make this the index field. Index fields
 146          * are currently used by Kopete::Contact::serialize to autoset the index
 147          * when possible.
 148          *
 149          * Only one field can be index field. Calling this method multiple times
 150          * as index field will reset the value of index field!
 151          */
 152         void addAddressBookField( const QString &field, AddressBookFieldAddMode mode = AddOnly );
 153
 154         /**
 155          * @brief Prepare for unloading a plugin
 156          *
 157          * When unloading a plugin the plugin manager first calls aboutToUnload()
 158          * to indicate the pending unload. Some plugins need time to shutdown
 159          * asynchronously and thus can't be simply deleted in the destructor.
 160          *
 161          * The default implementation immediately emits the @ref readyForUnload() signal,
 162          * which basically makes the shutdown immediate and synchronous. If you need
 163          * more time you can reimplement this method and fire the signal whenever
 164          * you're ready. (you have 3 seconds)
 165          *
 166          * @ref Kopete::Protocol reimplement it.
 167          */
 168         virtual void aboutToUnload();
 169
 170 signals:
 171         /**
 172          * Notify that the settings of a plugin were changed.
 173          * These changes are passed on from the new KCDialog code in kdelibs/kutils.
 174          */
 175         void settingsChanged();
 176
 177         /**
 178          * Indicate when we're ready for unload.
 179          * @see aboutToUnload()
 180          */
 181         void readyForUnload();
 182
 183 public slots:
 184
 185         /**
 186          * deserialize() and tell the plugin
 187          * to apply the previously stored data again.
 188          * This method is also responsible for retrieving the settings from the
 189          * address book. Settings that were registered can be retrieved with
 190          * @ref Kopete::MetaContact::addressBookField().
 191          *
 192          * The default implementation does nothing.
 193          *
 194          * @todo we probably should think to another way to save the contacltist.
 195          */
 196         virtual void deserialize( MetaContact *metaContact, const QMap<QString, QString> &data );
 197
 198 private:
 199         class Private;
 200         Private *d;
 201 };
 202
 203
 204 } //END namespace Kopete
 205
 206
 207 #endif