KParts

plugin.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 1999 Simon Hausmann <hausm[email protected]>
4  SPDX-FileCopyrightText: 1999 David Faure <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 #ifndef PLUGIN_H
9 #define PLUGIN_H
10 
11 #include <kparts/kparts_export.h>
12 
13 #include <KXMLGUIClient>
14 #include <QDomElement>
15 #include <QObject>
16 #include <memory>
17 
18 #if KPARTS_BUILD_DEPRECATED_SINCE(5, 77)
19 class KAboutData;
20 #endif
21 class KPluginMetaData;
22 
23 namespace KParts
24 {
25 class PluginPrivate;
26 
27 /**
28  * @class Plugin plugin.h <KParts/Plugin>
29  *
30  * @short A plugin is the way to add actions to an existing KParts application,
31  * or to a Part.
32  *
33  * The XML of those plugins looks exactly like of the shell or parts,
34  * with one small difference: The document tag should have an additional
35  * attribute, named "library", and contain the name of the library implementing
36  * the plugin.
37  *
38  * If you want this plugin to be used by a part, you need to
39  * install the rc file under the directory
40  * "data" (KDEDIR/share/apps usually)+"/instancename/kpartplugins/"
41  * where instancename is the name of the part's instance.
42  *
43  * You should also install a "plugin info" .desktop file with the same name.
44  * \see KPluginInfo
45  */
46 class KPARTS_EXPORT Plugin : public QObject, virtual public KXMLGUIClient
47 {
48  Q_OBJECT
49 public:
50  struct PluginInfo {
51  QString m_relXMLFileName; // relative filename, i.e. kpartplugins/name
52  QString m_absXMLFileName; // full path of most recent filename matching the relative
53  // filename
54  QDomDocument m_document;
55  };
56 
57  /**
58  * Construct a new KParts plugin.
59  */
60  explicit Plugin(QObject *parent = nullptr);
61  /**
62  * Destructor.
63  */
64  ~Plugin() override;
65 
66  /**
67  * Reimplemented for internal reasons
68  */
69  QString xmlFile() const override;
70 
71  /**
72  * Reimplemented for internal reasons
73  */
74  QString localXMLFile() const override;
75 
76  /**
77  * Load the plugin libraries from the directories appropriate
78  * to @p instance and make the Plugin objects children of @p parent.
79  *
80  * It is recommended to use the last loadPlugins method instead,
81  * to support enabling and disabling of plugins.
82  */
83  static void loadPlugins(QObject *parent, const QString &instance);
84 
85  /**
86  * Load the plugin libraries specified by the list @p docs and make the
87  * 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 QList<PluginInfo> &pluginInfos);
93 
94  /**
95  * Load the plugin libraries specified by the list @p pluginInfos, make the
96  * Plugin objects children of @p parent, and use the given @p instance.
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, const QString &instance);
102 
103  /**
104  * Load the plugin libraries for the given @p instance, make the
105  * Plugin objects children of @p parent, and insert the plugin as a child GUI client
106  * of @p parentGUIClient.
107  *
108  * This method uses the KConfig object of the given instance, to find out which
109  * plugins are enabled and which are disabled. What happens by default (i.e.
110  * for new plugins that are not in that config file) is controlled by
111  * @p enableNewPluginsByDefault. It can be overridden by the plugin if it
112  * sets the X-KDE-PluginInfo-EnabledByDefault key in the .desktop file
113  * (with the same name as the .rc file)
114  *
115  * If a disabled plugin is already loaded it will be removed from the GUI
116  * factory and deleted.
117  *
118  * If you change the binary interface offered by your part, you can avoid crashes
119  * from old plugins lying around by setting X-KDE-InterfaceVersion=2 in the
120  * .desktop files of the plugins, and passing 2 to @p interfaceVersionRequired, so that
121  * the old plugins are not loaded. Increase both numbers every time a
122  * binary incompatible change in the application's plugin interface is made.
123  *
124  *
125  * This method is automatically called by KParts::Part and by KParts::MainWindow.
126  * @see PartBase::setPluginLoadingMode, PartBase::setPluginInterfaceVersion
127  *
128  * If you call this method in an already constructed GUI (like when the user
129  * has changed which plugins are enabled) you need to add the new plugins to
130  * the KXMLGUIFactory:
131  * \code
132  * if( factory() )
133  * {
134  * const QList<KParts::Plugin *> plugins = KParts::Plugin::pluginObjects( this );
135  * for ( KParts::Plugin * plugin : plugins )
136  * factory()->addClient( plugin );
137  * }
138  * \endcode
139  */
140  static void loadPlugins(QObject *parent,
141  KXMLGUIClient *parentGUIClient,
142  const QString &instance,
143  bool enableNewPluginsByDefault = true,
144  int interfaceVersionRequired = 0);
145 
146  /**
147  * Returns a list of plugin objects loaded for @p parent. This
148  * functions basically iterates over the children of the given object
149  * and returns those that inherit from KParts::Plugin.
150  **/
151  static QList<Plugin *> pluginObjects(QObject *parent);
152 
153 protected:
154 #if KPARTS_BUILD_DEPRECATED_SINCE(5, 77)
155  /**
156  * @deprecated Since 5.77, use setMetaData(const KPluginMetaData&) instead.
157  */
158  KPARTS_DEPRECATED_VERSION(5, 77, "Use setMetaData(const KPluginMetaData&) instead")
159  virtual void setComponentData(const KAboutData &pluginData);
160 #endif
161 
162  /**
163  * @since 5.77
164  */
165  void setMetaData(const KPluginMetaData &metaData);
166 
167 private:
168  /**
169  * Look for plugins in the @p instance's "data" directory (+"/kpartplugins")
170  *
171  * @return A list of QDomDocument s, containing the parsed xml documents returned by plugins.
172  */
173  static QList<Plugin::PluginInfo> pluginInfos(const QString &instance);
174 
175  /**
176  * @internal
177  * @return The plugin created from the library @p libname
178  */
179  static Plugin *loadPlugin(QObject *parent, const QString &libname, const QString &keyword = QString());
180 
181 private:
182  static bool hasPlugin(QObject *parent, const QString &library);
183  std::unique_ptr<PluginPrivate> const d;
184 };
185 
186 }
187 
188 #endif
The KParts namespace,.
A plugin is the way to add actions to an existing KParts application, or to a Part.
Definition: plugin.h:46
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Nov 28 2021 22:49:37 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.