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

KDE's Doxygen guidelines are available online.