summaryrefslogtreecommitdiffstats
path: root/kontact/interfaces/plugin.h
diff options
context:
space:
mode:
Diffstat (limited to 'kontact/interfaces/plugin.h')
-rw-r--r--kontact/interfaces/plugin.h291
1 files changed, 291 insertions, 0 deletions
diff --git a/kontact/interfaces/plugin.h b/kontact/interfaces/plugin.h
new file mode 100644
index 000000000..c80227984
--- /dev/null
+++ b/kontact/interfaces/plugin.h
@@ -0,0 +1,291 @@
+/*
+ This file is part of KDE Kontact.
+
+ Copyright (c) 2001 Matthias Hoelzer-Kluepfel <mhk@kde.org>
+ Copyright (c) 2002-2003 Daniel Molkentin <molkentin@kde.org>
+ Copyright (c) 2003 Cornelius Schumacher <schumacher@kde.org>
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public License
+ along with this library; see the file COPYING.LIB. If not, write to
+ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+*/
+
+#ifndef KONTACT_PLUGIN_H
+#define KONTACT_PLUGIN_H
+
+#include <qobject.h>
+#include <kxmlguiclient.h>
+#include <kdepimmacros.h>
+#include <qptrlist.h>
+
+class QStringList;
+class DCOPClient;
+class DCOPObject;
+class KAboutData;
+class KAction;
+class KConfig;
+class QWidget;
+namespace KParts { class ReadOnlyPart; }
+
+/**
+ Increase this version number whenever you make a change
+ in the API.
+ */
+#define KONTACT_PLUGIN_VERSION 6
+
+namespace Kontact
+{
+
+class Core;
+class Summary;
+
+/**
+ Base class for all Plugins in Kontact. Inherit from it
+ to get a plugin. It can insert an icon into the sidepane,
+ add widgets to the widgetstack and add menu items via XMLGUI.
+ */
+class KDE_EXPORT Plugin : public QObject, virtual public KXMLGUIClient
+{
+ Q_OBJECT
+
+ public:
+ /**
+ Creates a new Plugin, note that name parameter name is required if
+ you want your plugin to do dcop via it's own instance of
+ DCOPClient by calling dcopClient.
+ @note name MUST be the name of the application that
+ provides the part! This is the name used for DCOP registration.
+ It's ok to have several plugins using the same application name.
+ */
+ Plugin( Core *core, QObject *parent, const char *name );
+
+ ~Plugin();
+
+ /**
+ Sets the identifier.
+ */
+ void setIdentifier( const QString &identifier );
+
+ /**
+ Returns the identifier. It is used as argument for several
+ methods of Kontacts core.
+ */
+ QString identifier() const;
+
+ /**
+ Sets the localized title.
+ */
+ void setTitle( const QString &title );
+
+ /**
+ Returns the localized title.
+ */
+ QString title() const;
+
+ /**
+ Sets the icon name.
+ */
+ void setIcon( const QString &icon );
+
+ /**
+ Returns the icon name.
+ */
+ QString icon() const;
+
+ /**
+ Sets the name of executable (if existant).
+ */
+ void setExecutableName( const QString &bin );
+
+ /**
+ Returns the name of the binary (if existant).
+ */
+ QString executableName() const;
+
+ /**
+ Set name of library which contains the KPart used by this plugin.
+ */
+ void setPartLibraryName( const QCString & );
+
+ /**
+ Create the DCOP interface for the given @p serviceType, if this
+ plugin provides it. Return false otherwise.
+ */
+ virtual bool createDCOPInterface( const QString& /*serviceType*/ ) { return false; }
+
+ /**
+ Reimplement this method and return wether a standalone application is still running
+ This is only required if your part is also available as standalone application.
+ */
+ virtual bool isRunningStandalone() { return false; }
+
+ /**
+ Reimplement this method if your application needs a different approach to be brought
+ in the foreground. The default behaviour is calling the binary.
+ This is only required if your part is also available as standalone application.
+ */
+ virtual void bringToForeground();
+
+ /**
+ Reimplement this method if you want to add your credits to the Kontact
+ about dialog.
+ */
+ virtual const KAboutData *aboutData();
+
+ /**
+ You can use this method if you need to access the current part. You can be
+ sure that you always get the same pointer as long as the part has not been
+ deleted.
+ */
+ KParts::ReadOnlyPart *part();
+
+ /**
+ Reimplement this method and return the a path relative to "data" to the tips file.
+ */
+ virtual QString tipFile() const;
+
+ /**
+ This function is called when the plugin is selected by the user before the
+ widget of the KPart belonging to the plugin is raised.
+ */
+ virtual void select();
+
+ /**
+ This function is called whenever the config dialog has been closed
+ successfully.
+ */
+ virtual void configUpdated();
+
+ /**
+ Reimplement this method if you want to add a widget for your application
+ to Kontact's summary page.
+ */
+ virtual Summary *createSummaryWidget( QWidget * /*parent*/ ) { return 0; }
+
+ /**
+ Returns wether the plugin provides a part that should be shown in the sidebar.
+ */
+ virtual bool showInSideBar() const;
+
+ /**
+ Set if the plugin provides a part that should be shown in the sidebar.
+ */
+ void setShowInSideBar( bool hasPart );
+
+ /**
+ Reimplement this method if you want to add checks before closing down the main kontact
+ window. Return true if it's OK to close the window. If any loaded plugin returns false
+ from this method, then the main kontact window will not close.
+ */
+ virtual bool queryClose() const { return true; }
+
+ /**
+ Retrieve the current DCOP Client for the plugin.
+
+ The clients name is taken from the name argument in the constructor.
+ @note: The DCOPClient object will only be created when this method is
+ called for the first time. Make sure that the part has been loaded
+ before calling this method, if it's the one that contains the DCOP
+ interface that other parts might use.
+ */
+ DCOPClient *dcopClient() const;
+
+ /**
+ Return the weight of the plugin. The higher the weight the lower it will
+ be displayed in the sidebar. The default implementation returns 0.
+ */
+ virtual int weight() const { return 0; }
+
+ /**
+ Insert "New" action.
+ */
+ void insertNewAction( KAction *action );
+
+ /**
+ Insert "Sync" action.
+ */
+ void insertSyncAction( KAction *action );
+
+ /**
+ FIXME: write API doc for Kontact::Plugin::newActions().
+ */
+ QPtrList<KAction>* newActions() const;
+
+ /**
+ FIXME: write API doc for Kontact::Plugin::syncActions().
+ */
+ QPtrList<KAction>* syncActions() const;
+
+ /**
+ Returns a list of action name which shall be hidden in the main toolbar.
+ */
+ virtual QStringList invisibleToolbarActions() const { return QStringList(); }
+
+ /**
+ Return, if the plugin can handle the drag object of the given mime type.
+ */
+ virtual bool canDecodeDrag( QMimeSource * ) { return false; }
+
+ /**
+ Process drop event.
+ */
+ virtual void processDropEvent( QDropEvent * ) {}
+
+ virtual void loadProfile( const QString& directoryPath );
+
+ virtual void saveToProfile( const QString& directoryPath ) const;
+
+ /**
+ * Session management: read properties
+ */
+ virtual void readProperties( KConfig * ) {}
+
+ /**
+ * Session management: save properties
+ */
+ virtual void saveProperties( KConfig * ) {}
+
+ Core *core() const;
+
+ bool disabled() const;
+ void setDisabled( bool v );
+
+ public slots:
+ /**
+ internal usage
+ */
+ void slotConfigUpdated();
+
+ protected:
+ /**
+ Reimplement and return the part here. Reimplementing createPart() is
+ mandatory!
+ */
+ virtual KParts::ReadOnlyPart *createPart() = 0;
+
+ KParts::ReadOnlyPart *loadPart();
+
+ virtual void virtual_hook( int id, void* data );
+
+ private slots:
+ void partDestroyed();
+
+ private:
+ class Private;
+ Private *d;
+};
+
+}
+
+#endif