Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 217 insertions, 0 deletions

diff --git a/kopete/libkopete/kopeteplugin.h b/kopete/libkopete/kopeteplugin.h
new file mode 100644
index 00000000..43a80849
--- /dev/null
+++ b/kopete/libkopete/kopeteplugin.h
@@ -0,0 +1,217 @@
+/*
+    kopeteplugin.h - Kopete Plugin API
+
+    Copyright (c) 2001-2002 by Duncan Mac-Vicar Prett <duncan@kde.org>
+    Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
+    Copyright (c) 2002-2004 by Olivier Goffart        <ogoffart@ tiscalinet.be>
+
+    Copyright (c) 2002-2003 by the Kopete developers  <kopete-devel@kde.org>
+
+    *************************************************************************
+    *                                                                       *
+    * This library is free software; you can redistribute it and/or         *
+    * modify it under the terms of the GNU Lesser General Public            *
+    * License as published by the Free Software Foundation; either          *
+    * version 2 of the License, or (at your option) any later version.      *
+    *                                                                       *
+    *************************************************************************
+*/
+
+#ifndef KOPETEPLUGIN_H
+#define KOPETEPLUGIN_H
+
+#include <kxmlguiclient.h>
+#include <qobject.h>
+#include <kdemacros.h>
+
+#include "kopete_export.h"
+
+#include <kopetemessage.h> //TODO: remove
+namespace DOM  { class Node; }  //TODO: remove
+class KAction; //TODO: remove
+
+
+class KPluginInfo;
+
+
+namespace Kopete
+{
+
+class MetaContact;
+
+/**
+ * @brief Base class for all plugins or protocols.
+ *
+ * To create a plugin, you need to create a .desktop file which looks like that:
+ * \verbatim
+[Desktop Entry]
+Encoding=UTF-8
+Type=Service
+X-Kopete-Version=1000900
+Icon=icon
+ServiceTypes=Kopete/Plugin
+X-KDE-Library=kopete_myplugin
+X-KDE-PluginInfo-Author=Your Name
+X-KDE-PluginInfo-Email=your@mail.com
+X-KDE-PluginInfo-Name=kopete_myplugin
+X-KDE-PluginInfo-Version=0.0.1
+X-KDE-PluginInfo-Website=http://yoursite.com
+X-KDE-PluginInfo-Category=Plugins
+X-KDE-PluginInfo-Depends=
+X-KDE-PluginInfo-License=GPL
+X-KDE-PluginInfo-EnabledByDefault=false
+Name=MyPlugin
+Comment=Plugin that do some nice stuff
+ \endverbatim
+ *
+ * The constructor of your plugin should looks like this:
+ *
+ * \code
+	typedef KGenericFactory<MyPlugin> MyPluginFactory;
+	static const KAboutData aboutdata("kopete_myplugin", I18N_NOOP("MyPlugin") , "1.0" );
+	K_EXPORT_COMPONENT_FACTORY( kopete_myplugin, MyPluginFactory( &aboutdata )  )
+
+	MyPlugin::MyPlugin( QObject *parent, const char *name, const QStringList &  args  )
+		: Kopete::Plugin( MyPluginFactory::instance(), parent, name )
+	{
+		//...
+	}
+ \endcode
+ *
+ * Kopete::Plugin inherits from KXMLGUIClient.  That client is added
+ * to the Kopete's mainwindow KXMLGUIFactory. So you may add actions
+ * on the main window (for hinstance in the meta contact popup menu).
+ * Please note the the client is added right after the plugin is created.
+ * so you have to create every actions in the constructor
+ *
+ * @author Duncan Mac-Vicar P. <duncan@kde.org>
+ * @author Olivier Goffart <ogoffart @ tiscalinet.be>
+ */
+class KOPETE_EXPORT Plugin : public QObject, public KXMLGUIClient
+{
+	Q_OBJECT
+
+public:
+	Plugin( KInstance *instance, QObject *parent, const char *name );
+	virtual ~Plugin();
+
+	/**
+	 * Returns the KPluginInfo object associated with this plugin
+	 */
+	KPluginInfo *pluginInfo() const;
+
+	/**
+	 * Get the name of the icon for this plugin. The icon name is taken from the
+	 * .desktop file.
+	 *
+	 * May return an empty string if the .desktop file for this plugin specifies
+	 * no icon name to use.
+	 *
+	 * This is a convenience method that simply calls @ref pluginInfo()->icon().
+	 */
+	QString pluginIcon() const;
+
+	/**
+	 * Returns the display name of this plugin.
+	 *
+	 * This is a convenience method that simply calls @ref pluginInfo()->name().
+	 */
+	QString displayName() const;
+
+	/**
+	 * @brief Get the plugin id
+	 * @return the plugin's id which is gotten by calling QObject::className().
+	 */
+	QString pluginId() const;
+
+	/**
+	 * Return the list of all keys from the address book in which the plugin
+	 * is interested. Those keys are monitored for changes upon load and
+	 * during runtime. When the key actually changes, the plugin's
+	 * addressBookKeyChanged( Kopete::MetaContact *mc, const QString &key )
+	 * is called.
+	 * You can add fields to the list using @ref addAddressBookField()
+	 */
+	QStringList addressBookFields() const;
+
+	/**
+	 * Return the index field as set by @ref addAddressBookField()
+	 */
+	QString addressBookIndexField() const;
+
+	/**
+	 * Mode for an address book field as used by @ref addAddressBookField()
+	 */
+	enum AddressBookFieldAddMode { AddOnly, MakeIndexField };
+
+	/**
+	 * Add a field to the list of address book fields. See also @ref addressBookFields()
+	 * for a description of the fields.
+	 *
+	 * Set mode to MakeIndexField to make this the index field. Index fields
+	 * are currently used by Kopete::Contact::serialize to autoset the index
+	 * when possible.
+	 *
+	 * Only one field can be index field. Calling this method multiple times
+	 * as index field will reset the value of index field!
+	 */
+	void addAddressBookField( const QString &field, AddressBookFieldAddMode mode = AddOnly );
+
+	/**
+	 * @brief Prepare for unloading a plugin
+	 *
+	 * When unloading a plugin the plugin manager first calls aboutToUnload()
+	 * to indicate the pending unload. Some plugins need time to shutdown
+	 * asynchronously and thus can't be simply deleted in the destructor.
+	 *
+	 * The default implementation immediately emits the @ref readyForUnload() signal,
+	 * which basically makes the shutdown immediate and synchronous. If you need
+	 * more time you can reimplement this method and fire the signal whenever
+	 * you're ready. (you have 3 seconds)
+	 *
+	 * @ref Kopete::Protocol reimplement it.
+	 */
+	virtual void aboutToUnload();
+
+signals:
+	/**
+	 * Notify that the settings of a plugin were changed.
+	 * These changes are passed on from the new KCDialog code in kdelibs/kutils.
+	 */
+	void settingsChanged();
+
+	/**
+	 * Indicate when we're ready for unload.
+	 * @see aboutToUnload()
+	 */
+	void readyForUnload();
+
+public slots:
+
+	/**
+	 * deserialize() and tell the plugin
+	 * to apply the previously stored data again.
+	 * This method is also responsible for retrieving the settings from the
+	 * address book. Settings that were registered can be retrieved with
+	 * @ref Kopete::MetaContact::addressBookField().
+	 *
+	 * The default implementation does nothing.
+	 *
+	 * @todo we probably should think to another way to save the contacltist.
+	 */
+	virtual void deserialize( MetaContact *metaContact, const QMap<QString, QString> &data );
+
+
+protected:
+	virtual void virtual_hook( uint id, void *data );
+
+private:
+	class Private;
+	Private *d;
+};
+
+
+} //END namespace Kopete
+
+
+#endif