1/* This file is part of the KDE project
2 Copyright (C) 1999 Simon Hausmann <hausmann@kde.org>
3 (C) 1999 David Faure <faure@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20#ifndef PLUGIN_H
21#define PLUGIN_H
22
23#include <QtXml/QDomElement>
24#include <QtCore/QObject>
25#include <kaction.h>
26#include <kxmlguiclient.h>
27
28#include <kparts/kparts_export.h>
29
30class KComponentData;
31
32namespace KParts
33{
34
35/**
36 * A plugin is the way to add actions to an existing KParts application,
37 * or to a Part.
38 *
39 * The XML of those plugins looks exactly like of the shell or parts,
40 * with one small difference: The document tag should have an additional
41 * attribute, named "library", and contain the name of the library implementing
42 * the plugin.
43 *
44 * If you want this plugin to be used by a part, you need to
45 * install the rc file under the directory
46 * "data" (KDEDIR/share/apps usually)+"/instancename/kpartplugins/"
47 * where instancename is the name of the part's instance.
48 *
49 * You should also install a "plugin info" .desktop file with the same name.
50 * \see KPluginInfo
51 *
52 * For a tutorial on how to write plugins, see http://developer.kde.org/documentation/tutorials/developing-a-plugin-structure/index.html#developing_plugins
53 */
54class KPARTS_EXPORT Plugin : public QObject, virtual public KXMLGUIClient
55{
56 Q_OBJECT
57public:
58 struct PluginInfo
59 {
60 QString m_relXMLFileName; // relative filename, i.e. kpartplugins/name
61 QString m_absXMLFileName; // full path of most recent filename matching the relative
62 // filename
63 QDomDocument m_document;
64 };
65
66 /**
67 * Construct a new KParts plugin.
68 */
69 Plugin( QObject* parent = 0 );
70 /**
71 * Destructor.
72 */
73 virtual ~Plugin();
74
75 /**
76 * Reimplemented for internal reasons
77 */
78 virtual QString xmlFile() const;
79
80 /**
81 * Reimplemented for internal reasons
82 */
83 virtual QString localXMLFile() const;
84
85 /**
86 * Load the plugin libraries from the directories appropriate
87 * to @p instance and make the Plugin objects children of @p parent.
88 *
89 * It is recommended to use the last loadPlugins method instead,
90 * to support enabling and disabling of plugins.
91 */
92 static void loadPlugins( QObject *parent, const KComponentData &instance );
93
94 /**
95 * Load the plugin libraries specified by the list @p docs and make the
96 * Plugin objects children of @p parent .
97 *
98 * It is recommended to use the last loadPlugins method instead,
99 * to support enabling and disabling of plugins.
100 */
101 static void loadPlugins( QObject *parent, const QList<PluginInfo> &pluginInfos );
102
103 /**
104 * Load the plugin libraries specified by the list @p pluginInfos, make the
105 * Plugin objects children of @p parent, and use the given @p instance.
106 *
107 * It is recommended to use the last loadPlugins method instead,
108 * to support enabling and disabling of plugins.
109 */
110 static void loadPlugins( QObject *parent, const QList<PluginInfo> &pluginInfos, const KComponentData &instance );
111
112 /**
113 * Load the plugin libraries for the given @p instance, make the
114 * Plugin objects children of @p parent, and insert the plugin as a child GUI client
115 * of @p parentGUIClient.
116 *
117 * This method uses the KConfig object of the given instance, to find out which
118 * plugins are enabled and which are disabled. What happens by default (i.e.
119 * for new plugins that are not in that config file) is controlled by
120 * @p enableNewPluginsByDefault. It can be overridden by the plugin if it
121 * sets the X-KDE-PluginInfo-EnabledByDefault key in the .desktop file
122 * (with the same name as the .rc file)
123 *
124 * If a disabled plugin is already loaded it will be removed from the GUI
125 * factory and deleted.
126 *
127 * If you change the binary interface offered by your part, you can avoid crashes
128 * from old plugins lying around by setting X-KDE-InterfaceVersion=2 in the
129 * .desktop files of the plugins, and passing 2 to @p interfaceVersionRequired, so that
130 * the old plugins are not loaded. Increase both numbers every time a
131 * binary incompatible change in the application's plugin interface is made.
132 *
133 *
134 * This method is automatically called by KParts::Part and by KParts::MainWindow.
135 * @see PartBase::setPluginLoadingMode, PartBase::setPluginInterfaceVersion
136 *
137 * If you call this method in an already constructed GUI (like when the user
138 * has changed which plugins are enabled) you need to add the new plugins to
139 * the KXMLGUIFactory:
140 * \code
141 * if( factory() )
142 * {
143 * const QList<KParts::Plugin *> plugins = KParts::Plugin::pluginObjects( this );
144 * foreach ( KParts::Plugin * plugin, plugins )
145 * factory()->addClient( plugin );
146 * }
147 * \endcode
148 */
149 static void loadPlugins(QObject *parent, KXMLGUIClient* parentGUIClient,
150 const KComponentData &instance, bool enableNewPluginsByDefault = true,
151 int interfaceVersionRequired = 0);
152
153 /**
154 * Returns a list of plugin objects loaded for @p parent. This
155 * functions basically iterates over the children of the given object
156 * and returns those that inherit from KParts::Plugin.
157 **/
158 static QList<Plugin *> pluginObjects( QObject *parent );
159
160protected:
161 /**
162 * Look for plugins in the @p instance's "data" directory (+"/kpartplugins")
163 *
164 * @return A list of QDomDocument s, containing the parsed xml documents returned by plugins.
165 */
166 static QList<Plugin::PluginInfo> pluginInfos(const KComponentData &instance);
167
168 /**
169 * @internal
170 * @return The plugin created from the library @p libname
171 */
172#ifndef KDE_NO_DEPRECATED
173 KDE_DEPRECATED static Plugin* loadPlugin( QObject * parent, const char* libname );
174#endif
175
176 /**
177 * @internal, added only for source compatibility
178 * @return The plugin created from the library @p libname
179 */
180#ifndef KDE_NO_DEPRECATED
181 KDE_DEPRECATED static Plugin* loadPlugin( QObject * parent, const QByteArray &libname );
182#endif
183
184 /**
185 * @internal
186 * @return The plugin created from the library @p libname
187 */
188 static Plugin* loadPlugin( QObject * parent, const QString &libname );
189
190 static Plugin* loadPlugin( QObject * parent, const QString &libname, const QString &keyword );
191
192 virtual void setComponentData(const KComponentData &instance);
193
194private:
195 static bool hasPlugin( QObject* parent, const QString& library );
196 class PluginPrivate;
197 PluginPrivate* const d;
198};
199
200}
201
202#endif
203