interfaces/iplugin.h

   1 /* This file is part of the KDE project
   2    Copyright 1999-2001 Bernd Gehrmann <bernd@kdevelop.org>
   3    Copyright 2004,2007 Alexander Dymo <adymo@kdevelop.org>
   4    Copyright 2006 Adam Treat <treat@kde.org>
   5    Copyright 2007 Andreas Pakulat <apaku@gmx.de>
   6
   7    This library is free software; you can redistribute it and/or
   8    modify it under the terms of the GNU Library General Public
   9    License as published by the Free Software Foundation; either
  10    version 2 of the License, or (at your option) any later version.
  11
  12    This library is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15    Library General Public License for more details.
  16
  17    You should have received a copy of the GNU Library General Public License
  18    along with this library; see the file COPYING.LIB.  If not, write to
  19    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20    Boston, MA 02110-1301, USA.
  21 */
  22 #ifndef IPLUGIN_H
  23 #define IPLUGIN_H
  24
  25 #include <QtCore/QObject>
  26 #include <kxmlguiclient.h>
  27
  28 #include <QtCore/QList>
  29 #include <QtCore/QPointer>
  30 #include <QtCore/QPair>
  31 #include <QtDesigner/QExtensionManager>
  32 #include "interfacesexport.h"
  33
  34 class KIconLoader;
  35 class QAction;
  36
  37 /**
  38  * Current KDevelop plugin interface version. Interfaces declare plugin version
  39  * to make sure old source (or binary) incompatible plugins are not loaded.
  40  * Increase this if it is necessary that old plugins stop working.
  41  */
  42 #define KDEVELOP_PLUGIN_VERSION 6
  43
  44 /**
  45  * This macro adds an extension interface to register with the extension manager
  46  * Call this macro for all interfaces your plugin implements in its constructor
  47  */
  48
  49 #define KDEV_USE_EXTENSION_INTERFACE( Extension ) \
  50     addExtension( Q_TYPEID( Extension ) );
  51
  52 namespace KDevelop
  53 {
  54
  55 class ICore;
  56 class Context;
  57 class ContextMenuExtension;
  58
  59 /**
  60  * The base class for all KDevelop plugins.
  61  *
  62  * Plugin is a component which is loaded into KDevelop shell at startup or by
  63  * request. Each plugin should have corresponding .desktop file with a
  64  * description. The .desktop file template looks like:
  65  * @code
  66  * [Desktop Entry]
  67  * Encoding=UTF-8
  68  * Type=Service
  69  * Name=
  70  * GenericName=
  71  * Comment=
  72  * Icon=
  73  * X-KDevelop-Plugin-Version=
  74  * X-KDevelop-Plugin-Homepage=
  75  * X-KDevelop-Plugin-BugsEmailAddress=
  76  * X-KDevelop-Plugin-Copyright=
  77  * X-KDE-Library=
  78  * X-KDevelop-Version=
  79  * X-KDevelop-Category=
  80  * X-KDevelop-Properties=
  81  * X-KDevelop-Args=
  82  * @endcode
  83  * <b>Description of parameters in .desktop file:</b>
  84  * - <i>Name</i> is a non-translatable name of a plugin, it is used in KTrader
  85  * queries to search for a plugin (required);
  86  * - <i>GenericName</i> is a translatable name of a plugin, it is used to show
  87  * plugin names in GUI (required);
  88  * - <i>Comment</i> is a short description about the plugin (optional);
  89  * - <i>Icon</i> is a plugin icon (preferred);
  90  * - <i>X-KDevelop-Plugin-Version</i> is a version of a plugin (optional);
  91  * - <i>X-KDevelop-Interfaces</i> is a list of extension interfaces that this
  92  * plugin implements (optional);
  93  * - <i>X-KDevelop-IRequired</i> is a list of extension interfaces that this
  94  * plugin depends on (optional);
  95  * - <i>X-KDevelop-IOptional</i> is a list of extension interfaces that this
  96  * plugin will use if they are available (optional);
  97  * - <i>X-KDevelop-Plugin-Homepage</i> is a home page of a plugin (optional);
  98  * - <i>X-KDevelop-Plugin-License</i> is a license (optional). can be: GPL,
  99  * LGPL, BSD, Artistic, QPL or Custom. If this property is not set, license is
 100  * considered as unknown;
 101  * - <i>X-KDevelop-Plugin-BugsEmailAddress</i> is an email address for bug
 102  * reports (optional);
 103  * - <i>X-KDevelop-Plugin-Copyright</i> is a copyright statement (optional);
 104  * - <i>X-KDE-Library</i> is a name of library which contains the plugin
 105  * (required);
 106  * - <i>X-KDevelop-Version</i> is a version of KDevelop interfaces which is
 107  * supported by the plugin (required);
 108  * - <i>X-KDevelop-Category</i> is a scope of a plugin (see below for
 109  * explanation) (required);
 110  * - <i>X-KDevelop-Args</i> is a list of additional arguments passed to plugins
 111  * constructor (optional);
 112  * - <i>X-KDevelop-Properties</i> is a list of properties which this plugin
 113  * supports, see the Profile documentation for an explanation (required to work
 114  * with shells that support profiles).
 115  *
 116  * Plugin scope can be either:
 117  * - Global
 118  * - Project
 119  * .
 120  * Global plugins are plugins which require only the shell to be loaded and do not operate on
 121  * the Project interface and/or do not use project wide information.\n
 122  * Core plugins are global plugins which offer some important "core" functionality and thus
 123  * are not selectable by user in plugin configuration pages.\n
 124  * Project plugins require a project to be loaded and are usually loaded/unloaded along with
 125  * the project.
 126  * If your plugin uses the Project interface and/or operates on project-related
 127  * information then this is a project plugin.
 128  *
 129  *
 130  * @sa Core class documentation for an information about features which are available to
 131  * plugins from shell applications.
 132  */
 133 class KDEVPLATFORMINTERFACES_EXPORT IPlugin: public QObject, public KXMLGUIClient
 134 {
 135     Q_OBJECT
 136
 137 public:
 138     /**Constructs a plugin.
 139      * @param instance The instance for this plugin.
 140      * @param parent The parent object for the plugin.
 141      */
 142     IPlugin(const KComponentData &instance, QObject *parent);
 143
 144     /**Destructs a plugin.*/
 145     virtual ~IPlugin();
 146
 147     /**
 148      * Signal the plugin that it should cleanup since it will be unloaded soon.
 149      */
 150     Q_SCRIPTABLE virtual void unload();
 151
 152     /**
 153      * Provides access to the global icon loader
 154      * @return the plugin's icon loader
 155      */
 156     Q_SCRIPTABLE KIconLoader* iconLoader() const;
 157
 158     Q_SCRIPTABLE ICore *core() const;
 159
 160     Q_SCRIPTABLE void registerExtensions();
 161     Q_SCRIPTABLE void unregisterExtensions();
 162
 163     Q_SCRIPTABLE QStringList extensions() const;
 164
 165     template<class Extension> Extension* extension()
 166     {
 167         return qt_extension<Extension*>( extensionManager(), this );
 168     }
 169
 170     /**
 171      * ask the plugin for a ContextActionContainer, which contains actions
 172      * that will be merged into the context menu.
 173      * @param context the context describing where the context menu was requested
 174      * @returns a container descriping which actions to merge into which context menu part
 175      */
 176     virtual ContextMenuExtension contextMenuExtension( KDevelop::Context* context );
 177
 178 public Q_SLOTS:
 179     /**
 180      * Re-initialize the global icon loader
 181      */
 182     void newIconLoader() const;
 183
 184 protected:
 185     void addExtension( const QString& );
 186
 187     /**
 188      * Initialize the XML Gui State.
 189      */
 190     virtual void initializeGuiState();
 191
 192 private:
 193     Q_PRIVATE_SLOT(d, void _k_guiClientAdded(KXMLGUIClient *))
 194     Q_PRIVATE_SLOT(d, void _k_updateState())
 195
 196     friend class IPluginPrivate;
 197     class IPluginPrivate* const d;
 198     QExtensionManager* extensionManager();
 199 };
 200
 201 }
 202 #endif
 203