You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
202 lines
8.9 KiB
202 lines
8.9 KiB
/* This file is part of the KDE project
|
|
Copyright (C) 1999-2001 Bernd Gehrmann <bernd@kdevelop.org>
|
|
Copyright (C) 2004 Alexander Dymo <adymo@kdevelop.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 TDEVPLUGIN_H
|
|
#define TDEVPLUGIN_H
|
|
|
|
#include <tqobject.h>
|
|
#include <kxmlguiclient.h>
|
|
#include "tdevapi.h"
|
|
|
|
class TDevCore;
|
|
class TDevProject;
|
|
class TDevVersionControl;
|
|
class TDevLanguageSupport;
|
|
class TDevPartController;
|
|
class TDevMainWindow;
|
|
class TDevCodeRepository;
|
|
class CodeModel;
|
|
class TDevPluginInfo;
|
|
class TQDomElement;
|
|
|
|
/**
|
|
@file tdevplugin.h
|
|
TDevelop plugin interface.
|
|
*/
|
|
|
|
/**Current TDevelop 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 TDEVELOP_PLUGIN_VERSION 5
|
|
|
|
/**
|
|
The base class for all TDevelop plugins.
|
|
Plugin is a component which is loaded into TDevelop 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-TDevelop-Plugin-Version=
|
|
X-TDevelop-Plugin-Homepage=
|
|
X-TDevelop-Plugin-BugsEmailAddress=
|
|
X-TDevelop-Plugin-Copyright=
|
|
X-TDE-Library=
|
|
X-TDevelop-Version=
|
|
X-TDevelop-Scope=
|
|
X-TDevelop-Properties=
|
|
X-TDevelop-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 TDETrader 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-TDevelop-Plugin-Version</i> is a version of a plugin (optional);
|
|
- <i>X-TDevelop-Plugin-Homepage</i> is a home page of a plugin (optional);
|
|
- <i>X-TDevelop-Plugin-License</i> is a license (optional). can be: GPL, LGPL, BSD, Artistic,
|
|
TQPL or Custom. If this property is not set, license is considered as unknown;
|
|
- <i>X-TDevelop-Plugin-BugsEmailAddress</i> is an email address for bug reports (optional);
|
|
- <i>X-TDevelop-Plugin-Copyright</i> is a copyright statement (optional);
|
|
- <i>X-TDE-Library</i> is a name of library which contains the plugin (required);
|
|
- <i>X-TDevelop-Version</i> is a version of TDevelop interfaces which is supported by the plugin (required);
|
|
- <i>X-TDevelop-Scope</i> is a scope of a plugin (see below for explanation) (required);
|
|
- <i>X-TDevelop-Args</i> is a list of additional arguments passed to plugins constructor (optional);
|
|
- <i>X-TDevelop-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 TDevProject 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 TDevProject interface and/or operate on project-related information then this is the project plugin.
|
|
|
|
@sa TDevGenericFactory class documentation for an information about plugin instantiation
|
|
and writing factories for plugins.
|
|
|
|
@sa TDevCore class documentation for an information about features which are available to plugins
|
|
from shell applications.
|
|
*/
|
|
class TDevPlugin: public TQObject, 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 TDevApi
|
|
interface. Otherwise the plugin will not be constructed.
|
|
@param name The internal name which identifies the plugin.*/
|
|
TDevPlugin(const TDevPluginInfo *info, TQObject *parent, const char *name = 0);
|
|
|
|
/**Destructs a plugin.*/
|
|
virtual ~TDevPlugin();
|
|
|
|
/**Provides an information about the plugin.
|
|
@return TDEAboutData object which was initialized in the constructor.*/
|
|
const TDevPluginInfo* info();
|
|
|
|
/**@return A reference to the toplevel widget.*/
|
|
TDevMainWindow *mainWindow();
|
|
|
|
/**@return A reference to the application core - an object which provides
|
|
basic functionalities for inter-parts communications / cooperation.*/
|
|
TDevCore *core() const;
|
|
|
|
/**@return A reference to the current project component or 0 if no project is loaded.*/
|
|
TDevProject *project() const;
|
|
|
|
/**@return A reference to the language support component or 0 if no support available.*/
|
|
TDevLanguageSupport *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.*/
|
|
TQDomDocument *projectDom() const;
|
|
|
|
/**@return A reference to the part controller which is used to manipulate loaded KParts.*/
|
|
TDevPartController *partController() const;
|
|
|
|
/**@return A reference to the plugin controller which is used to manipulate loaded plugin.*/
|
|
virtual TDevPluginController *pluginController() const;
|
|
|
|
/**@return A reference to the code repository (accessor to persistent symbol stores).*/
|
|
TDevCodeRepository* 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 TDevPlugin.
|
|
@param serviceType The service type of an extension (like "TDevelop/SourceFormatter").
|
|
@param constraint The constraint which is applied when quering for the service. This
|
|
constraint is a usual TDETrader constraint statement (like "[X-TDevelop-Foo]=='MyFoo'").
|
|
@return A KDevelop extension plugin for given service type or 0 if no plugin supports it*/
|
|
template <class Extension>
|
|
Extension *extension(const TQString &serviceType, const TQString &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 (tdeveloprc)
|
|
@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 TQDomElement* el);
|
|
|
|
/**Saves session settings.
|
|
@sa restorePartialProjectSession - this is the other way round, the same just for saving.*/
|
|
virtual void savePartialProjectSession(TQDomElement* el);
|
|
|
|
private:
|
|
TDevPlugin *extension_internal(const TQString &serviceType, const TQString &constraint = "");
|
|
|
|
TDevApi *m_api;
|
|
class Private;
|
|
Private *d;
|
|
};
|
|
|
|
#endif
|