KParts

plugin.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 1999 Simon Hausmann <[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 #if KPARTS_ENABLE_DEPRECATED_SINCE(5, 90)
14 
15 #include <KXMLGUIClient>
16 #include <QDomElement>
17 #include <QObject>
18 #include <memory>
19 
20 #if KPARTS_BUILD_DEPRECATED_SINCE(5, 77)
21 class KAboutData;
22 #endif
23 class KPluginMetaData;
24 
25 namespace KParts
26 {
27 class PluginPrivate;
28 
29 /**
30  * @class Plugin plugin.h <KParts/Plugin>
31  *
32  * @short A plugin is the way to add actions to an existing KParts application,
33  * or to a Part.
34  *
35  * The XML of those plugins looks exactly like of the shell or parts,
36  * with one small difference: The document tag should have an additional
37  * attribute, named "library", and contain the name of the library implementing
38  * the plugin.
39  *
40  * If you want this plugin to be used by a part, you need to
41  * install the rc file under the directory
42  * "data" (KDEDIR/share/apps usually)+"/instancename/kpartplugins/"
43  * where instancename is the name of the part's instance.
44  *
45  * You should also install a "plugin info" .desktop file with the same name.
46  * \see KPluginInfo
47  * @deprecated Since 5.90, the concept of KPart plugins is deprecated.
48  * In the Konqueror KF5Konq lib is a reimplementation of this class, which is not deprecated.
49  * Consider porting your usage to this class or import the plugin in Konqueror.
50  */
51 class KPARTS_EXPORT Plugin : public QObject, virtual public KXMLGUIClient
52 {
53  Q_OBJECT
54 public:
55  struct PluginInfo {
56  QString m_relXMLFileName; // relative filename, i.e. kpartplugins/name
57  QString m_absXMLFileName; // full path of most recent filename matching the relative
58  // filename
59  QDomDocument m_document;
60  };
61 
62  /**
63  * Construct a new KParts plugin.
64  */
65  KPARTS_DEPRECATED_VERSION(5, 90, "See class API docs")
66  explicit Plugin(QObject *parent = nullptr);
67  /**
68  * Destructor.
69  */
70  ~Plugin() override;
71 
72  /**
73  * Reimplemented for internal reasons
74  */
75  QString xmlFile() const override;
76 
77  /**
78  * Reimplemented for internal reasons
79  */
80  QString localXMLFile() const override;
81 
82  /**
83  * Load the plugin libraries from the directories appropriate
84  * to @p instance and make the Plugin objects children of @p parent.
85  *
86  * It is recommended to use the last loadPlugins method instead,
87  * to support enabling and disabling of plugins.
88  */
89  KPARTS_DEPRECATED_VERSION(5, 90, "See class API docs")
90  static void loadPlugins(QObject *parent, const QString &instance);
91 
92  /**
93  * Load the plugin libraries specified by the list @p docs and make the
94  * Plugin objects children of @p parent .
95  *
96  * It is recommended to use the last loadPlugins method instead,
97  * to support enabling and disabling of plugins.
98  */
99  KPARTS_DEPRECATED_VERSION(5, 90, "See class API docs")
100  static void loadPlugins(QObject *parent, const QList<PluginInfo> &pluginInfos);
101 
102  /**
103  * Load the plugin libraries specified by the list @p pluginInfos, make the
104  * Plugin objects children of @p parent, and use the given @p instance.
105  *
106  * It is recommended to use the last loadPlugins method instead,
107  * to support enabling and disabling of plugins.
108  */
109  KPARTS_DEPRECATED_VERSION(5, 90, "See class API docs")
110  static void loadPlugins(QObject *parent, const QList<PluginInfo> &pluginInfos, const QString &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  * for ( KParts::Plugin * plugin : plugins )
145  * factory()->addClient( plugin );
146  * }
147  * \endcode
148  */
149  KPARTS_DEPRECATED_VERSION(5, 90, "See class API docs")
150  static void loadPlugins(QObject *parent,
151  KXMLGUIClient *parentGUIClient,
152  const QString &instance,
153  bool enableNewPluginsByDefault = true,
154  int interfaceVersionRequired = 0);
155 
156  /**
157  * Returns a list of plugin objects loaded for @p parent. This
158  * functions basically iterates over the children of the given object
159  * and returns those that inherit from KParts::Plugin.
160  **/
161  KPARTS_DEPRECATED_VERSION(5, 90, "See class API docs")
162  static QList<Plugin *> pluginObjects(QObject *parent);
163 
164 protected:
165 #if KPARTS_BUILD_DEPRECATED_SINCE(5, 77)
166  /**
167  * @deprecated Since 5.77, use setMetaData(const KPluginMetaData&) instead.
168  */
169  KPARTS_DEPRECATED_VERSION(5, 77, "Use setMetaData(const KPluginMetaData&) instead")
170  virtual void setComponentData(const KAboutData &pluginData);
171 #endif
172 
173  /**
174  * @since 5.77
175  */
176  void setMetaData(const KPluginMetaData &metaData);
177 
178 private:
179  /**
180  * Look for plugins in the @p instance's "data" directory (+"/kpartplugins")
181  *
182  * @return A list of QDomDocument s, containing the parsed xml documents returned by plugins.
183  */
184  KPARTS_DEPRECATED_VERSION(5, 90, "See class API docs")
185  static QList<Plugin::PluginInfo> pluginInfos(const QString &instance);
186 
187  /**
188  * @internal
189  * @return The plugin created from the library @p libname
190  */
191  KPARTS_DEPRECATED_VERSION(5, 90, "See class API docs")
192  static Plugin *loadPlugin(QObject *parent, const QString &libname, const QString &keyword = QString());
193 
194 private:
195  static bool hasPlugin(QObject *parent, const QString &library);
196  std::unique_ptr<PluginPrivate> const d;
197 };
198 
199 }
200 
201 #endif
202 #endif
A plugin is the way to add actions to an existing KParts application, or to a Part.
Definition: plugin.h:51
The KParts namespace,.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Mon Aug 15 2022 03:59:46 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.