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)",
91  "ServiceTypes": [
92  "KMyMoney/Plugin"
93  ],
95  }
96  }
97  * @endcode
98  *
99  * This example assumes you are using
100  * @code{.cmake}
101  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/... ${CMAKE_CURRENT_BINARY_DIR}/... @ONLY)
102  @endcode
103  * to replace the version variables using cmake.
104  *
105  * @see https://doc.qt.io/qt-5/plugins-howto.html
106  * @see https://api.kde.org/frameworks/kcoreaddons/html/classKPluginMetaData.html
107  *
108  */
109 class KMM_PLUGIN_EXPORT Plugin : public QObject, public KXMLGUIClient
110 {
111  Q_OBJECT
112 public:
113 #if KCOREADDONS_VERSION < QT_VERSION_CHECK(5, 77, 0)
114  explicit Plugin(QObject* parent, const QVariantList& args);
115 #else
116  explicit Plugin(QObject* parent, const KPluginMetaData& metaData, const QVariantList& args);
117 #endif
118  virtual ~Plugin();
119 
120  QString componentDisplayName() const;
121 
122 public Q_SLOTS:
123  /**
124  * @brief Called during plug in process
125  */
126  virtual void plug(KXMLGUIFactory* guiFactory);
127 
128  /**
129  * @brief Called before unloading
130  */
131  virtual void unplug();
132 
133  /**
134  * This method is called by the application whenever a
135  * selection changes. The default implementation does nothing.
136  */
137  virtual void updateActions(const SelectedObjects& selections);
138 
139  /**
140  * This method is called by the application whenever the
141  * configuration changes. The default implementation does nothing.
142  */
143  virtual void updateConfiguration();
144 
145 protected:
146  /** See KMyMoneyApp::toggleAction() for a description */
147  KToggleAction* toggleAction(const QString& name) const;
148 
149  // define interface classes here. The interface classes provide a mechanism
150  // for the plugin to interact with KMyMoney
151  // they are defined in the following form for an interface
152  // named Xxx:
153  //
154  // XxxInterface* xxxInterface();
155 
156  AppInterface* appInterface() const;
157  ViewInterface* viewInterface() const;
158  StatementInterface* statementInterface() const;
159  ImportInterface* importInterface() const;
160 
161 private:
162  QString m_componentDisplayName;
163 };
164 
165 /**
166  * This class describes the interface between the KMyMoney
167  * application and it's ONLINE-BANKING plugins. All online banking plugins
168  * must provide this interface.
169  *
170  * A good tutorial on how to design and develop a plugin
171  * structure for a KDE application (e.g. KMyMoney) can be found at
172  * http://web.archive.org/web/20100305214125/http://developer.kde.org/documentation/tutorials/developing-a-plugin-structure/index.html
173  *
174  */
175 class KMM_PLUGIN_EXPORT OnlinePlugin
176 {
177 public:
178  OnlinePlugin();
179  virtual ~OnlinePlugin();
180 
181  virtual void protocols(QStringList& protocolList) const = 0;
182 
183  /**
184  * This method returns a pointer to a widget representing an additional
185  * tab that will be added to the KNewAccountDlg. The string referenced
186  * with @a tabName will be filled with the text that should be placed
187  * on the tab. It should return 0 if no additional tab is needed.
188  *
189  * Information about the account can be taken out of @a account.
190  *
191  * Once the pointer to the widget is returned to KMyMoney, it takes care
192  * of destruction of all included widgets when the dialog is closed. The plugin
193  * can access the widgets created after the call to storeConfigParameters()
194  * happened.
195  */
196  virtual QWidget* accountConfigTab(const MyMoneyAccount& account, QString& tabName) = 0;
197 
198  /**
199  * This method is called by the framework whenever it is time to store
200  * the configuration data maintained by the plugin. The plugin should use
201  * the widgets created in accountConfigTab() to extract the current values.
202  *
203  * @param current The @a current container contains the current settings
204  */
205  virtual MyMoneyKeyValueContainer onlineBankingSettings(const MyMoneyKeyValueContainer& current) = 0;
206 
207  /**
208  * This method is called by the framework when the user wants to map
209  * a KMyMoney account onto an online account. The KMyMoney account is identified
210  * by @a acc and the online provider should store its data in @a onlineBankingSettings
211  * upon success.
212  *
213  * @retval true if account is mapped
214  * @retval false if account is not mapped
215  */
216  virtual bool mapAccount(const MyMoneyAccount& acc, MyMoneyKeyValueContainer& onlineBankingSettings) = 0;
217 
218  /**
219  * This method is called by the framework when the user wants to update
220  * a KMyMoney account with data from an online account. The KMyMoney account is identified
221  * by @a acc. The online provider should read its data from acc.onlineBankingSettings().
222  * @a true is returned upon success. The plugin might consider to stack the requests
223  * in case @a moreAccounts is @p true. @a moreAccounts defaults to @p false.
224  *
225  * @retval true if account is updated
226  * @retval false if account is not updated
227  */
228  virtual bool updateAccount(const MyMoneyAccount& acc, bool moreAccounts = false) = 0;
229 };
230 
231 /**
232  * This class describes the interface between the KMyMoney
233  * application and it's IMPORTER plugins. All importer plugins
234  * must provide this interface.
235  *
236  * A good tutorial on how to design and develop a plugin
237  * structure for a KDE application (e.g. KMyMoney) can be found at
238  * http://web.archive.org/web/20100305214125/http://developer.kde.org/documentation/tutorials/developing-a-plugin-structure/index.html
239  *
240  */
241 class KMM_PLUGIN_EXPORT ImporterPlugin
242 {
243 public:
244  ImporterPlugin();
245  virtual ~ImporterPlugin();
246 
247  /**
248  * This method returns the list of the MIME types that this plugin handles,
249  * e.g. {"application/x-ofx", "application/x-qfx"}. Be specific: don't use generic
250  * types, like "text/plain", which many other types inherit from, and which
251  * would result in @ref isMyFormat() returning false positives.
252  *
253  * @return QStringList List of MIME types
254  */
255  virtual QStringList formatMimeTypes() const = 0;
256 
257  /**
258  * This method checks whether the file provided is of expected format.
259  * The default implementation checks whether the file's MIME type inherits any
260  * of the types provided by @ref formatMimeTypes().
261  *
262  * @param filename Fully-qualified pathname to a file
263  *
264  * @return bool Whether the indicated file is importable by this plugin
265  */
266  virtual bool isMyFormat(const QString& filename) const;
267 
268  /**
269  * Import a file
270  *
271  * @param filename File to import
272  *
273  * @return bool Whether the import was successful.
274  */
275  virtual bool import(const QString& filename) = 0;
276 
277  /**
278  * Returns the error result of the last import
279  *
280  * @return QString English-language name of the error encountered in the
281  * last import, or QString() if it was successful.
282  *
283  */
284  virtual QString lastError() const = 0;
285 };
286 
287 /**
288  * This class describes the interface between the KMyMoney
289  * application and it's STORAGE plugins. All storage plugins
290  * must provide this interface.
291  *
292  */
293 class KMM_PLUGIN_EXPORT StoragePlugin
294 {
295 public:
296  StoragePlugin() = default;
297  virtual ~StoragePlugin() = default;
298 
299  /**
300  * @brief Loads file into storage
301  * @param url URL of the file
302  * @return true if successfully opened
303  */
304  virtual bool open(const QUrl& url) = 0;
305 
306  /**
307  * @brief Saves storage into file
308  * @param url URL of the file
309  * @return true if successfully saved
310  */
311  virtual bool save(const QUrl& url) = 0;
312 
313  /**
314  * @brief Saves storage into file
315  * @param url URL of the file
316  * @return true if successfully saved
317  */
318  virtual bool saveAs() = 0;
319 
320  /**
321  * @brief Storage identifier
322  * @return Storage identifier
323  */
324  virtual eKMyMoney::StorageType storageType() const = 0;
325 
326  virtual QString fileExtension() const = 0;
327 
328  /**
329  * @brief returns the full URL used to open the database (incl. password)
330  * @return QUrl to re-open the database
331  */
332  virtual QUrl openUrl() const = 0;
333 };
334 
335 /**
336  * This class describes the interface between the KMyMoney
337  * application and its data plugins. All data plugins
338  * must provide this interface.
339  *
340  */
341 class KMM_PLUGIN_EXPORT DataPlugin
342 {
343 public:
344  DataPlugin() = default;
345  virtual ~DataPlugin() = default;
346 
347  /**
348  * @brief Gets data from data service
349  * @param arg Item name to retrieve data for
350  * @param type Data type to retrieve for item
351  * @return a data like int or QString
352  */
353  virtual QVariant requestData(const QString& arg, uint type) = 0;
354 };
355 
357 
358 /**
359  * @brief The Container struct to hold all plugin interfaces
360  */
361 struct Container {
362  QMap<QString, Plugin*> standard; // this should contain all loaded plugins because every plugin should inherit Plugin class
363  QMap<QString, OnlinePlugin*> online; // casted standard plugin, if such interface is available
364  QMap<QString, OnlinePluginExtended*> extended; // casted standard plugin, if such interface is available
365  QMap<QString, ImporterPlugin*> importer; // casted standard plugin, if such interface is available
366  QMap<QString, StoragePlugin*> storage; // casted standard plugin, if such interface is available
367  QMap<QString, DataPlugin*> data; // casted standard plugin, if such interface is available
368 };
369 
370 } // end of namespace
371 
372 /**
373  * @brief Structure of plugins objects by their interfaces
374  */
375 KMM_PLUGIN_EXPORT extern KMyMoneyPlugin::Container pPlugins;
376 
377 Q_DECLARE_INTERFACE(KMyMoneyPlugin::OnlinePlugin, "org.kmymoney.plugin.onlineplugin")
378 Q_DECLARE_INTERFACE(KMyMoneyPlugin::ImporterPlugin, "org.kmymoney.plugin.importerplugin")
379 Q_DECLARE_INTERFACE(KMyMoneyPlugin::StoragePlugin, "org.kmymoney.plugin.storageplugin")
380 Q_DECLARE_INTERFACE(KMyMoneyPlugin::DataPlugin, "org.kmymoney.plugin.dataplugin")
381 
382 /** @} */
383 
384 #endif
This class describes the interface between the KMyMoney application and it&#39;s IMPORTER plugins...
KMM_PLUGIN_EXPORT KMyMoneyPlugin::Container pPlugins
Structure of plugins objects by their interfaces.
This abstract class represents the ImportInterface to add new importers to KMyMoney.
This abstract class represents the ViewInterface to add new view pages to the JanusWidget of KMyMoney...
Definition: viewinterface.h:47
Interface between KMyMoney and Online Banking plugins for executing transactions. ...
This class describes the interface between the KMyMoney application and it&#39;s STORAGE plugins...
This class describes the interface between the KMyMoney application and it&#39;s ONLINE-BANKING plugins...
The Container struct to hold all plugin interfaces.
This class describes the interface between the KMyMoney application and its data plugins.
This class describes the interface between KMyMoney and it&#39;s plugins.
This abstract class represents the interface to import statements into the KMyMoney application...
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Oct 19 2021 23:23:38 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.