iplugincontroller.h 7.95 KB
Newer Older
1
/* This file is part of the KDE project
2
3
4
Copyright 2004, 2007 Alexander Dymo <adymo@kdevelop.org>
Copyright 2006 Matt Rogers <mattr@kde.org>
Copyright 2007 Andreas Pakulat <apaku@gmx.de>
5
6

Based on code from Kopete
7
Copyright 2002-2003 Martijn Klingens <klingens@kde.org>
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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.
*/
24
25
#ifndef KDEVPLATFORM_IPLUGINCONTROLLER_H
#define KDEVPLATFORM_IPLUGINCONTROLLER_H
26

27
28
#include <QObject>
#include <QList>
29
#include <QVector>
30
#include <QVariant>
31

32
#include <KPluginMetaData>
33

34
35
#include "iplugin.h"
#include "interfacesexport.h"
36
37
38
39
40
41
42
43
44
45
46

class QExtensionManager;

namespace KDevelop
{
class ProfileEngine;

/**
 * The KDevelop plugin controller.
 * The Plugin controller is responsible for querying, loading and unloading
 * available plugins.
47
48
49
 *
 * Most of the time if you want to get at a plugin you should be using
 * extensionForPlugin with the extension interface name. If you need to get at
50
51
 * the actual \c IPlugin* pointer to connect signals/slots you should use
 * \c pluginForExtension() and then the IPlugin's extension member function to get
52
53
54
 * at the extension interface if necessary.
 *
 * If you have the need to load a specific plugin for a given extension both
Pino Toscano's avatar
Pino Toscano committed
55
56
 * functions have an optional second parameter that allows one to specify the
 * name of the plugin as declared in the \c .desktop file under the
57
 * \c X-KDE-PluginInfo-Name property. This should be used only very seldomly in
58
 * real code and is mostly meant for testing and for implementation in the
59
 * shell as it makes the code dependent on the plugin name which may change and
60
 * also the actual plugin implementation so users cannot exchange one plugin
61
 * with another also implementing the same interface.
62
 *
63
64
65
66
67
68
69
 */
class KDEVPLATFORMINTERFACES_EXPORT IPluginController : public QObject
{

Q_OBJECT

public:
Matt Rogers's avatar
Matt Rogers committed
70
71
72
73
    /**
     * \brief Indicates the plugin type
     * This is used to determine how the plugin is loaded
     */
74
    enum PluginType {
Matt Rogers's avatar
Matt Rogers committed
75
76
        Global = 0, ///< Indicates that the plugin is loaded at startup
        Project ///< Indicates that the plugin is loaded with the first opened project
77
78
    };

79
    explicit IPluginController( QObject* parent = nullptr );
80

81
    ~IPluginController() override;
82
83
84
85

    /**
     * Get the plugin info for a loaded plugin
     */
86
    virtual KPluginMetaData pluginInfo(const IPlugin*) const = 0;
87

Milian Wolff's avatar
Milian Wolff committed
88
89
90
91
92
    /**
     * Find the KPluginMetaData structure for the given @p pluginId.
     */
    virtual KPluginMetaData infoForPluginId(const QString &pluginId) const = 0;

93
94
95
    /**
     * Get a list of currently loaded plugins
     */
96
    virtual QList<IPlugin*> loadedPlugins() const = 0;
97
98
99
100
101
102
103

    /**
     * @brief Unloads the plugin specified by @p plugin
     *
     * @param plugin The name of the plugin as specified by the
     * X-KDE-PluginInfo-Name key of the .desktop file for the plugin
     */
104
    virtual bool unloadPlugin( const QString & plugin ) = 0;
105
106

    /**
107
     * @brief Loads the plugin specified by @p pluginName
108
109
110
111
     *
     * @param pluginName the name of the plugin, as given in the X-KDE-PluginInfo-Name property
     * @returns a pointer to the plugin instance or 0
     */
112
    virtual IPlugin* loadPlugin( const QString & pluginName ) = 0;
113
114

     /**
Matt Rogers's avatar
Matt Rogers committed
115
     * Retrieve a plugin which supports the given extension interface.
116
     *
117
     * All already loaded plugins will be queried and the first one to support the extension interface
Matt Rogers's avatar
Matt Rogers committed
118
     * will be returned. Any plugin can be an extension, only the "ServiceTypes=..." entry is
119
     * required in .desktop file for that plugin.
120
121
122
123
124
125
126
127
     *
     * If no already-loaded plugin was found, we try to load a plugin for the given extension.
     *
     * If no plugin was found, a nullptr will be returned.
     *
     * @param extension The extension interface. Can be empty if you want to find a plugin by name or other constraint.
     * @param pluginName The name of the plugin to load if multiple plugins for the extension exist, corresponds to the X-KDE-PluginInfo-Name
     * @param constraints A map of constraints on other plugin info properties.
128
129
     * @return A KDevelop extension plugin for given service type or 0 if no plugin supports it
     */
130
    virtual IPlugin *pluginForExtension(const QString &extension, const QString& pluginName = {}, const QVariantMap& constraints = QVariantMap()) = 0;
131

Matt Rogers's avatar
Matt Rogers committed
132
133
134
135
136
137
     /**
     * Retrieve a list of plugins which supports the given extension interface.
     * All already loaded plugins will be queried and the first one to support the extension interface
     * will be returned. Any plugin can be an extension, only the "ServiceTypes=..." entry is
     * required in .desktop file for that plugin.
     * @param extension The extension interface
138
     * @param constraints A map of constraints on other plugin info properties.
Matt Rogers's avatar
Matt Rogers committed
139
140
     * @return A KDevelop extension plugin for given service type or 0 if no plugin supports it
     */
Kevin Funk's avatar
Kevin Funk committed
141
    virtual QList<IPlugin*> allPluginsForExtension(const QString &extension, const QVariantMap& constraints = QVariantMap()) = 0;
142
143

     /**
144
     * Retrieve the plugin which supports given extension interface and
Matt Rogers's avatar
Matt Rogers committed
145
146
     * returns a pointer to the extension interface.
     *
147
148
149
150
     * All already loaded plugins will be queried and the first one to support the extension interface
     * will be returned. Any plugin can be an extension, only "ServiceTypes=..." entry is
     * required in .desktop file for that plugin.
     * @param extension The extension interface
151
     * @param pluginName The name of the plugin to load if multiple plugins for the extension exist, corresponds to the X-KDE-PluginInfo-Name
152
153
     * @return Pointer to the extension interface or 0 if no plugin supports it
      */
154
155
    template<class Extension> Extension* extensionForPlugin( const QString &extension = {}, const QString &pluginName = {})
    {
156
157
        QString ext;
        if( extension.isEmpty() ) {
158
            ext = QString::fromUtf8(qobject_interface_iid<Extension*>());
159
160
161
        } else {
            ext = extension;
        }
162
        IPlugin *plugin = pluginForExtension(ext, pluginName);
163
164
165
        if (plugin) {
            return plugin->extension<Extension>();
        }
Anton Anikin's avatar
Anton Anikin committed
166
        return nullptr;
167
168
169
    }

    /**
170
     * Query for plugin information on KDevelop plugins implementing the given extension.
Matt Rogers's avatar
Matt Rogers committed
171
172
173
     *
     * The service version is checked for automatically and the only serviceType
     * searched for is "KDevelop/Plugin"
174
175
176
     *
     * @param extension The extension that should be implemented by the plugin, i.e. listed in X-KDevelop-Interfaces.
     * @param constraints A map of constraints on other plugin info properties.
177
178
     * @return The list of plugin offers.
     */
179
    virtual QVector<KPluginMetaData> queryExtensionPlugins(const QString &extension, const QVariantMap& constraints = QVariantMap()) const = 0;
180

181
    virtual QList<ContextMenuExtension> queryPluginsForContextMenuExtensions(KDevelop::Context* context, QWidget* parent) const = 0;
182
183
184

Q_SIGNALS:
    void loadingPlugin( const QString& );
185
    void pluginLoaded( KDevelop::IPlugin* );
186
    void unloadingPlugin( KDevelop::IPlugin* );
187
    /**
188
     * This signal is emitted whenever a plugin is unloaded.
189
190
191
192
     * @note: that you shouldn't use the pointer anymore
     * except for comparing it against against other pointers. The plugin instance can already have been completely
     * deleted when this signal is emitted.
     */
193
    void pluginUnloaded( KDevelop::IPlugin* );
194

195
196
private:
    friend class IPlugin;
197
198
199
200
201
};

}
#endif