KMyMoney Plugin API

kmymoneyplugin.h
1 /*
2  SPDX-FileCopyrightText: 2005-2021 Thomas Baumgart <[email protected]>
3  SPDX-FileCopyrightText: 2015 Christian Dávid <[email protected]>
4  SPDX-FileCopyrightText: 2021 Dawid Wróbel <[email protected]>
5  SPDX-License-Identifier: GPL-2.0-or-later
6 */
7 
8 #ifndef KMYMONEYPLUGIN_H
9 #define KMYMONEYPLUGIN_H
10 
11 #include <kmm_plugin_export.h>
12 
13 // ----------------------------------------------------------------------------
14 // QT Includes
15 
16 #include <QMap>
17 #include <QObject>
18 
19 // ----------------------------------------------------------------------------
20 // KDE Includes
21 
22 #include <KXMLGUIClient>
23 
24 #include "kcoreaddons_version.h"
25 
26 class KToggleAction;
27 class KPluginMetaData;
28 
29 // ----------------------------------------------------------------------------
30 // Project Includes
31 
32 #include "mymoneykeyvaluecontainer.h"
33 
34 class MyMoneyStorageMgr;
35 class MyMoneyAccount;
36 class KMyMoneySettings;
37 class IMyMoneyOperationsFormat;
38 class SelectedObjects;
39 
40 namespace KMyMoneyPlugin {
41 class AppInterface;
42 class ImportInterface;
43 class StatementInterface;
44 class ViewInterface;
45 }
46 
47 namespace eKMyMoney {
48 enum class StorageType;
49 }
50 
51 /**
52  * @defgroup KMyMoneyPlugin
53  *
54  * KMyMoney knows several types of plugins. The most common and generic one is KMyMoneyPlugin::Plugin.
55  *
56  * Another group of plugins are just loaded on demand and offer special functions with a tight integration into KMyMoney. Whenever possible you should use this
57  * kind of plugins. At the moment this are the onlineTask and payeeIdentifierData.
58  *
59  * @{
60  */
61 
62 namespace KMyMoneyPlugin {
63 
64 /**
65  * This class describes the interface between KMyMoney and it's plugins.
66  *
67  * The plugins are based on Qt 5's plugin system. So you must compile json information into the plugin.
68  * KMyMoney looks into the folder "${PLUGIN_INSTALL_DIR}/kmymoney/" and loads all plugins found there (if the user did not deactivate the plugin).
69  *
70  * The json header of the plugin must comply with the requirements of KCoreAddon's KPluginMetaData class.
71  * To load the plugin at start up the service type "KMyMoney/Plugin" must be set.
72  *
73  * @warning The plugin system for KMyMoney 5 is still in development. Especially the loading of the on-demand plugins (mainly undocumented :( ) will change.
74  *
75  * A basic json header is shown below.
76  * @code{.json}
77  {
78  "KPlugin": {
79  "Authors": [
80  {
81  "Name": "Author's Names, Second Author",
82  "Email": "E-Mail 1, E-Mail 2"
83  }
84  ],
85  "Description": "Short description for plugin list (translateable)",
86  "EnabledByDefault": true,
87  "Icon": "icon to be shown in plugin list",
88  "Id": "a unique identifier",
89  "License": "see KPluginMetaData for list of predefined licenses (translateable)",
90  "Name": "Name of the plugin (translateable)",
92  }
93  }
94  * @endcode
95  *
96  * This example assumes you are using
97  * @code{.cmake}
98  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/... ${CMAKE_CURRENT_BINARY_DIR}/... @ONLY)
99  @endcode
100  * to replace the version variables using cmake.
101  *
102  * @see https://doc.qt.io/qt-5/plugins-howto.html
103  * @see https://api.kde.org/frameworks/kcoreaddons/html/classKPluginMetaData.html
104  *
105  */
106 class KMM_PLUGIN_EXPORT Plugin : public QObject, public KXMLGUIClient
107 {
108  Q_OBJECT
109 public:
110 #if KCOREADDONS_VERSION < QT_VERSION_CHECK(5, 77, 0)
111  explicit Plugin(QObject* parent, const QVariantList& args);
112 #else
113  explicit Plugin(QObject* parent, const KPluginMetaData& metaData, const QVariantList& args);
114 #endif
115  virtual ~Plugin();
116 
117  QString componentDisplayName() const;
118 
119 public Q_SLOTS:
120  /**
121  * @brief Called during plug in process
122  */
123  virtual void plug(KXMLGUIFactory* guiFactory);
124 
125  /**
126  * @brief Called before unloading
127  */
128  virtual void unplug();
129 
130  /**
131  * This method is called by the application whenever a
132  * selection changes. The default implementation does nothing.
133  */
134  virtual void updateActions(const SelectedObjects& selections);
135 
136  /**
137  * This method is called by the application whenever the
138  * configuration changes. The default implementation does nothing.
139  */
140  virtual void updateConfiguration();
141 
142 protected:
143  /** See KMyMoneyApp::toggleAction() for a description */
144  KToggleAction* toggleAction(const QString& name) const;
145 
146  // define interface classes here. The interface classes provide a mechanism
147  // for the plugin to interact with KMyMoney
148  // they are defined in the following form for an interface
149  // named Xxx:
150  //
151  // XxxInterface* xxxInterface();
152 
153  AppInterface* appInterface() const;
154  ViewInterface* viewInterface() const;
155  StatementInterface* statementInterface() const;
156  ImportInterface* importInterface() const;
157 
158 private:
159  QString m_componentDisplayName;
160 };
161 
162 /**
163  * This class describes the interface between the KMyMoney
164  * application and it's ONLINE-BANKING plugins. All online banking plugins
165  * must provide this interface.
166  *
167  * A good tutorial on how to design and develop a plugin
168  * structure for a KDE application (e.g. KMyMoney) can be found at
169  * http://web.archive.org/web/20100305214125/http://developer.kde.org/documentation/tutorials/developing-a-plugin-structure/index.html
170  *
171  */
172 class KMM_PLUGIN_EXPORT OnlinePlugin
173 {
174 public:
175  OnlinePlugin();
176  virtual ~OnlinePlugin();
177 
178  virtual void protocols(QStringList& protocolList) const = 0;
179 
180  /**
181  * This method returns a pointer to a widget representing an additional
182  * tab that will be added to the KNewAccountDlg. The string referenced
183  * with @a tabName will be filled with the text that should be placed
184  * on the tab. It should return 0 if no additional tab is needed.
185  *
186  * Information about the account can be taken out of @a account.
187  *
188  * Once the pointer to the widget is returned to KMyMoney, it takes care
189  * of destruction of all included widgets when the dialog is closed. The plugin
190  * can access the widgets created after the call to storeConfigParameters()
191  * happened.
192  */
193  virtual QWidget* accountConfigTab(const MyMoneyAccount& account, QString& tabName) = 0;
194 
195  /**
196  * This method is called by the framework whenever it is time to store
197  * the configuration data maintained by the plugin. The plugin should use
198  * the widgets created in accountConfigTab() to extract the current values.
199  *
200  * @param current The @a current container contains the current settings
201  */
202  virtual MyMoneyKeyValueContainer onlineBankingSettings(const MyMoneyKeyValueContainer& current) = 0;
203 
204  /**
205  * This method is called by the framework when the user wants to map
206  * a KMyMoney account onto an online account. The KMyMoney account is identified
207  * by @a acc and the online provider should store its data in @a onlineBankingSettings
208  * upon success.
209  *
210  * @retval true if account is mapped
211  * @retval false if account is not mapped
212  */
213  virtual bool mapAccount(const MyMoneyAccount& acc, MyMoneyKeyValueContainer& onlineBankingSettings) = 0;
214 
215  /**
216  * This method is called by the framework when the user wants to update
217  * a KMyMoney account with data from an online account. The KMyMoney account is identified
218  * by @a acc. The online provider should read its data from acc.onlineBankingSettings().
219  * @a true is returned upon success. The plugin might consider to stack the requests
220  * in case @a moreAccounts is @p true. @a moreAccounts defaults to @p false.
221  *
222  * @retval true if account is updated
223  * @retval false if account is not updated
224  */
225  virtual bool updateAccount(const MyMoneyAccount& acc, bool moreAccounts = false) = 0;
226 };
227 
228 /**
229  * This class describes the interface between the KMyMoney
230  * application and it's IMPORTER plugins. All importer plugins
231  * must provide this interface.
232  *
233  * A good tutorial on how to design and develop a plugin
234  * structure for a KDE application (e.g. KMyMoney) can be found at
235  * http://web.archive.org/web/20100305214125/http://developer.kde.org/documentation/tutorials/developing-a-plugin-structure/index.html
236  *
237  */
238 class KMM_PLUGIN_EXPORT ImporterPlugin
239 {
240 public:
241  ImporterPlugin();
242  virtual ~ImporterPlugin();
243 
244  /**
245  * This method returns the list of the MIME types that this plugin handles,
246  * e.g. {"application/x-ofx", "application/x-qfx"}. Be specific: don't use generic
247  * types, like "text/plain", which many other types inherit from, and which
248  * would result in @ref isMyFormat() returning false positives.
249  *
250  * @return QStringList List of MIME types
251  */
252  virtual QStringList formatMimeTypes() const = 0;
253 
254  /**
255  * This method checks whether the file provided is of expected format.
256  * The default implementation checks whether the file's MIME type inherits any
257  * of the types provided by @ref formatMimeTypes().
258  *
259  * @param filename Fully-qualified pathname to a file
260  *
261  * @return bool Whether the indicated file is importable by this plugin
262  */
263  virtual bool isMyFormat(const QString& filename) const;
264 
265  /**
266  * Import a file
267  *
268  * @param filename File to import
269  *
270  * @return bool Whether the import was successful.
271  */
272  virtual bool import(const QString& filename) = 0;
273 
274  /**
275  * Returns the error result of the last import
276  *
277  * @return QString English-language name of the error encountered in the
278  * last import, or QString() if it was successful.
279  *
280  */
281  virtual QString lastError() const = 0;
282 };
283 
284 /**
285  * This class describes the interface between the KMyMoney
286  * application and it's STORAGE plugins. All storage plugins
287  * must provide this interface.
288  *
289  */
290 class KMM_PLUGIN_EXPORT StoragePlugin
291 {
292 public:
293  StoragePlugin() = default;
294  virtual ~StoragePlugin() = default;
295 
296  /**
297  * @brief Loads file into storage
298  * @param url URL of the file
299  * @return true if successfully opened
300  */
301  virtual bool open(const QUrl& url) = 0;
302 
303  /**
304  * @brief Saves storage into file
305  * @param url URL of the file
306  * @return true if successfully saved
307  */
308  virtual bool save(const QUrl& url) = 0;
309 
310  /**
311  * @brief Saves storage into file
312  * @param url URL of the file
313  * @return true if successfully saved
314  */
315  virtual bool saveAs() = 0;
316 
317  /**
318  * @brief Storage identifier
319  * @return Storage identifier
320  */
321  virtual eKMyMoney::StorageType storageType() const = 0;
322 
323  virtual QString fileExtension() const = 0;
324 
325  /**
326  * @brief returns the full URL used to open the database (incl. password)
327  * @return QUrl to re-open the database
328  */
329  virtual QUrl openUrl() const = 0;
330 };
331 
332 /**
333  * This class describes the interface between the KMyMoney
334  * application and its data plugins. All data plugins
335  * must provide this interface.
336  *
337  */
338 class KMM_PLUGIN_EXPORT DataPlugin
339 {
340 public:
341  DataPlugin() = default;
342  virtual ~DataPlugin() = default;
343 
344  /**
345  * @brief Gets data from data service
346  * @param arg Item name to retrieve data for
347  * @param type Data type to retrieve for item
348  * @return a data like int or QString
349  */
350  virtual QVariant requestData(const QString& arg, uint type) = 0;
351 };
352 
354 
355 /**
356  * @brief The Container struct to hold all plugin interfaces
357  */
358 struct Container {
359  QMap<QString, Plugin*> standard; // this should contain all loaded plugins because every plugin should inherit Plugin class
360  QMap<QString, OnlinePlugin*> online; // casted standard plugin, if such interface is available
361  QMap<QString, OnlinePluginExtended*> extended; // casted standard plugin, if such interface is available
362  QMap<QString, ImporterPlugin*> importer; // casted standard plugin, if such interface is available
363  QMap<QString, StoragePlugin*> storage; // casted standard plugin, if such interface is available
364  QMap<QString, DataPlugin*> data; // casted standard plugin, if such interface is available
365 };
366 
367 } // end of namespace
368 
369 /**
370  * @brief Structure of plugins objects by their interfaces
371  */
372 KMM_PLUGIN_EXPORT extern KMyMoneyPlugin::Container pPlugins;
373 
374 Q_DECLARE_INTERFACE(KMyMoneyPlugin::OnlinePlugin, "org.kmymoney.plugin.onlineplugin")
375 Q_DECLARE_INTERFACE(KMyMoneyPlugin::ImporterPlugin, "org.kmymoney.plugin.importerplugin")
376 Q_DECLARE_INTERFACE(KMyMoneyPlugin::StoragePlugin, "org.kmymoney.plugin.storageplugin")
377 Q_DECLARE_INTERFACE(KMyMoneyPlugin::DataPlugin, "org.kmymoney.plugin.dataplugin")
378 
379 /** @} */
380 
381 #endif
This class describes the interface between KMyMoney and it's plugins.
This abstract class represents the ImportInterface to add new importers to KMyMoney.
This class describes the interface between the KMyMoney application and its data plugins.
Interface between KMyMoney and Online Banking plugins for executing transactions.
This class describes the interface between the KMyMoney application and it's IMPORTER plugins.
This class describes the interface between the KMyMoney application and it's STORAGE plugins.
KMM_PLUGIN_EXPORT KMyMoneyPlugin::Container pPlugins
Structure of plugins objects by their interfaces.
The Container struct to hold all plugin interfaces.
This abstract class represents the interface to import statements into the KMyMoney application.
This abstract class represents the ViewInterface to add new view pages to the JanusWidget of KMyMoney...
Definition: viewinterface.h:47
This class describes the interface between the KMyMoney application and it's ONLINE-BANKING plugins.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Wed Jun 29 2022 03:51:35 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.