tdevelop/lib/interfaces/tdevplugin.h

/* 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