KMyMoney Plugin API

kmymoneyplugin.h
1/*
2 SPDX-FileCopyrightText: 2005-2021 Thomas Baumgart <ipwizard@users.sourceforge.net>
3 SPDX-FileCopyrightText: 2015 Christian Dávid <christian-david@web.de>
4 SPDX-FileCopyrightText: 2021 Dawid Wróbel <me@dawidwrobel.com>
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
26class KToggleAction;
27class KPluginMetaData;
28
29// ----------------------------------------------------------------------------
30// Project Includes
31
32#include "mymoneykeyvaluecontainer.h"
33
34class MyMoneyStorageMgr;
35class MyMoneyAccount;
36class KMyMoneySettings;
37class IMyMoneyOperationsFormat;
38class SelectedObjects;
39
40namespace KMyMoneyPlugin {
41class AppInterface;
42class ImportInterface;
43class StatementInterface;
44class ViewInterface;
45}
46
47namespace eKMyMoney {
48enum 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
62namespace 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 */
106class KMM_PLUGIN_EXPORT Plugin : public QObject, public KXMLGUIClient
107{
108 Q_OBJECT
109public:
110 explicit Plugin(QObject* parent, const KPluginMetaData& metaData, const QVariantList& args);
111 virtual ~Plugin();
112
113 QString componentDisplayName() const;
114
115public 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
138protected:
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
154private:
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 */
168class KMM_PLUGIN_EXPORT OnlinePlugin
169{
170public:
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 */
234class KMM_PLUGIN_EXPORT ImporterPlugin
235{
236public:
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 */
286class KMM_PLUGIN_EXPORT StoragePlugin
287{
288public:
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 */
334class KMM_PLUGIN_EXPORT DataPlugin
335{
336public:
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 */
354struct 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 */
368KMM_PLUGIN_EXPORT extern KMyMoneyPlugin::Container pPlugins;
369
370Q_DECLARE_INTERFACE(KMyMoneyPlugin::OnlinePlugin, "org.kmymoney.plugin.onlineplugin")
371Q_DECLARE_INTERFACE(KMyMoneyPlugin::ImporterPlugin, "org.kmymoney.plugin.importerplugin")
372Q_DECLARE_INTERFACE(KMyMoneyPlugin::StoragePlugin, "org.kmymoney.plugin.storageplugin")
373Q_DECLARE_INTERFACE(KMyMoneyPlugin::DataPlugin, "org.kmymoney.plugin.dataplugin")
374
375/** @} */
376
377#endif
This class describes the interface between the KMyMoney application and its data plugins.
virtual QVariant requestData(const QString &arg, uint type)=0
Gets data from data service.
This abstract class represents the ImportInterface to add new importers to KMyMoney.
This class describes the interface between the KMyMoney application and it's IMPORTER plugins.
virtual QString lastError() const =0
Returns the error result of the last import.
virtual QStringList formatMimeTypes() const =0
This method returns the list of the MIME types that this plugin handles, e.g.
Interface between KMyMoney and Online Banking plugins for executing transactions.
This class describes the interface between the KMyMoney application and it's ONLINE-BANKING plugins.
virtual MyMoneyKeyValueContainer onlineBankingSettings(const MyMoneyKeyValueContainer &current)=0
This method is called by the framework whenever it is time to store the configuration data maintained...
virtual bool mapAccount(const MyMoneyAccount &acc, MyMoneyKeyValueContainer &onlineBankingSettings)=0
This method is called by the framework when the user wants to map a KMyMoney account onto an online a...
virtual QWidget * accountConfigTab(const MyMoneyAccount &account, QString &tabName)=0
This method returns a pointer to a widget representing an additional tab that will be added to the KN...
virtual bool updateAccount(const MyMoneyAccount &acc, bool moreAccounts=false)=0
This method is called by the framework when the user wants to update a KMyMoney account with data fro...
This class describes the interface between KMyMoney and it's plugins.
This abstract class represents the interface to import statements into the KMyMoney application.
This class describes the interface between the KMyMoney application and it's STORAGE plugins.
virtual bool saveAs()=0
Saves storage into file.
virtual eKMyMoney::StorageType storageType() const =0
Storage identifier.
virtual bool open(const QUrl &url)=0
Loads file into storage.
virtual bool save(const QUrl &url)=0
Saves storage into file.
virtual QUrl openUrl() const =0
returns the full URL used to open the database (incl.
This abstract class represents the ViewInterface to add new view pages to the JanusWidget of KMyMoney...
KMM_PLUGIN_EXPORT KMyMoneyPlugin::Container pPlugins
Structure of plugins objects by their interfaces.
The Container struct to hold all plugin interfaces.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:00:05 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.