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 | |
30 | class KComponentData; |
31 | |
32 | namespace 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 | */ |
54 | class KPARTS_EXPORT Plugin : public QObject, virtual public KXMLGUIClient |
55 | { |
56 | Q_OBJECT |
57 | public: |
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 | |
160 | protected: |
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 | |
194 | private: |
195 | static bool hasPlugin( QObject* parent, const QString& library ); |
196 | class PluginPrivate; |
197 | PluginPrivate* const d; |
198 | }; |
199 | |
200 | } |
201 | |
202 | #endif |
203 | |