diff options
Diffstat (limited to 'lib/interfaces/kdevplugin.h')
-rw-r--r-- | lib/interfaces/kdevplugin.h | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/lib/interfaces/kdevplugin.h b/lib/interfaces/kdevplugin.h new file mode 100644 index 00000000..b65b411f --- /dev/null +++ b/lib/interfaces/kdevplugin.h @@ -0,0 +1,200 @@ +/* This file is part of the KDE project + Copyright (C) 1999-2001 Bernd Gehrmann <[email protected]> + Copyright (C) 2004 Alexander Dymo <[email protected]> + + 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., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. +*/ +#ifndef KDEVPLUGIN_H +#define KDEVPLUGIN_H + +#include <qobject.h> +#include <kxmlguiclient.h> +#include "kdevapi.h" + +class KDevCore; +class KDevProject; +class KDevVersionControl; +class KDevLanguageSupport; +class KDevPartController; +class KDevMainWindow; +class KDevCodeRepository; +class CodeModel; +class KDevPluginInfo; +class QDomElement; + +/** +@file kdevplugin.h +KDevelop plugin interface. +*/ + +/**Current KDevelop plugin interface version. Interfaces declare plugin version to make sure +old source (or binary) incompatible plugins are not loaded. Increase this if +it is necessary that old plugins stop working.*/ +#define KDEVELOP_PLUGIN_VERSION 5 + +/** +The base class for all KDevelop plugins. +Plugin is a component which is loaded into KDevelop shell at startup or by request. +Each plugin should have corresponding .desktop file with a description. +.desktop file template looks like: +@code +[Desktop Entry] +Encoding=UTF-8 +Type=Service +Name= +GenericName= +Comment= +Icon= +X-KDevelop-Plugin-Version= +X-KDevelop-Plugin-Homepage= +X-KDevelop-Plugin-BugsEmailAddress= +X-KDevelop-Plugin-Copyright= +X-KDE-Library= +X-KDevelop-Version= +X-KDevelop-Scope= +X-KDevelop-Properties= +X-KDevelop-Args= +@endcode +<b>Description of parameters in .desktop file:</b> +- <i>Name</i> is a non-translatable name of a plugin, it is used in KTrader queries +to search for a plugin (required); +- <i>GenericName</i> is a translatable name of a plugin, it is used to show +plugin names in GUI (required); +- <i>Comment</i> is a short description about the plugin (optional); +- <i>Icon</i> is a plugin icon (preferred); +- <i>X-KDevelop-Plugin-Version</i> is a version of a plugin (optional); +- <i>X-KDevelop-Plugin-Homepage</i> is a home page of a plugin (optional); +- <i>X-KDevelop-Plugin-License</i> is a license (optional). can be: GPL, LGPL, BSD, Artistic, +QPL or Custom. If this property is not set, license is considered as unknown; +- <i>X-KDevelop-Plugin-BugsEmailAddress</i> is an email address for bug reports (optional); +- <i>X-KDevelop-Plugin-Copyright</i> is a copyright statement (optional); +- <i>X-KDE-Library</i> is a name of library which contains the plugin (required); +- <i>X-KDevelop-Version</i> is a version of KDevelop interfaces which is supported by the plugin (required); +- <i>X-KDevelop-Scope</i> is a scope of a plugin (see below for explanation) (required); +- <i>X-KDevelop-Args</i> is a list of additional arguments passed to plugins constructor (optional); +- <i>X-KDevelop-Properties</i> is a list of properties which this plugin supports, see @ref Profile class documentation for explanation (required to work with shells that support profiles). +. +Plugin scope can be either: +- Core +- Global +- Project +. +Global plugins are plugins which require only shell to be loaded and do not operate on @ref KDevProject interface and/or do not use project wide information.\n +Core plugins are global plugins which offer some important "core" functionality and thus +are not selectable by user in plugin configuration pages.\n +Project plugins require a project to be loaded and are usually loaded/unloaded among with the project. +If your plugin use @ref KDevProject interface and/or operate on project-related information then this is the project plugin. + +@sa KDevGenericFactory class documentation for an information about plugin instantiation +and writing factories for plugins. + +@sa KDevCore class documentation for an information about features which are available to plugins +from shell applications. +*/ +class KDevPlugin: public QObject, public KXMLGUIClient +{ + Q_OBJECT + +public: + /**Constructs a plugin. + @param info Important information about the plugin - plugin internal and generic + (GUI) name, description, a list of authors, etc. That information is used to show + plugin information in various places like "about application" dialog, plugin selector + dialog, etc. Plugin does not take ownership on info object, also its lifetime should + be equal to the lifetime of the plugin. + @param parent The parent object for the plugin. Parent object must implement @ref KDevApi + interface. Otherwise the plugin will not be constructed. + @param name The internal name which identifies the plugin.*/ + KDevPlugin(const KDevPluginInfo *info, QObject *parent, const char *name = 0); + + /**Destructs a plugin.*/ + virtual ~KDevPlugin(); + + /**Provides an information about the plugin. + @return KAboutData object which was initialized in the constructor.*/ + const KDevPluginInfo* info(); + + /**@return A reference to the toplevel widget.*/ + KDevMainWindow *mainWindow(); + + /**@return A reference to the application core - an object which provides + basic functionalities for inter-parts communications / cooperation.*/ + KDevCore *core() const; + + /**@return A reference to the current project component or 0 if no project is loaded.*/ + KDevProject *project() const; + + /**@return A reference to the language support component or 0 if no support available.*/ + KDevLanguageSupport *languageSupport() const; + + /**@return A reference to the memory symbol store.*/ + CodeModel *codeModel() const; + + /**@return A reference to the DOM tree that represents the project file or 0 if no project is loaded.*/ + QDomDocument *projectDom() const; + + /**@return A reference to the part controller which is used to manipulate loaded KParts.*/ + KDevPartController *partController() const; + + /**@return A reference to the plugin controller which is used to manipulate loaded plugin.*/ + virtual KDevPluginController *pluginController() const; + + /**@return A reference to the code repository (accessor to persistent symbol stores).*/ + KDevCodeRepository* codeRepository() const; + + /**Queries for the plugin which supports given service type (such plugins are called extensions in KDevelop). + All already loaded plugins will be queried and the <b>first loaded one</b> to support + the service type will be returned. Any plugin can be an extension, only "ServiceTypes=..." + entry is required in .desktop file for that plugin. + + Template argument is used as a type to cast the result to. This is done because extension + is usually derived from a certain base class and not directly from KDevPlugin. + @param serviceType The service type of an extension (like "KDevelop/SourceFormatter"). + @param constraint The constraint which is applied when quering for the service. This + constraint is a usual KTrader constraint statement (like "[X-KDevelop-Foo]=='MyFoo'"). + @return A KDevelop extension plugin for given service type or 0 if no plugin supports it*/ + template <class Extension> + Extension *extension(const QString &serviceType, const QString &constraint = "") + { + return static_cast<Extension*>(extension_internal(serviceType, constraint)); + } + + /**Override this base class method to restore any settings which differs from project to project. + Data can be read from a certain subtree of the project session file. + During project loading, respectively project session (.kdevses) loading, + this method will be called to give a chance to adapt the plugin to + the newly loaded project. For instance, the debugger plugin might restore the + list of breakpoints from the previous debug session for the certain project. + @note Take attention to the difference to common not-project-related session stuff. + They belong to the application rc file (kdeveloprc) + @note Project session file is useful for settings which cannot be shared between + developers. If a setting should be shared, modify projectDom instead. + @param el The parent DOM element for plugins session settings.*/ + virtual void restorePartialProjectSession(const QDomElement* el); + + /**Saves session settings. + @sa restorePartialProjectSession - this is the other way round, the same just for saving.*/ + virtual void savePartialProjectSession(QDomElement* el); + +private: + KDevPlugin *extension_internal(const QString &serviceType, const QString &constraint = ""); + + KDevApi *m_api; + class Private; + Private *d; +}; + +#endif |