Akonadi

agentconfigurationbase.h
1 /*
2  SPDX-FileCopyrightText: 2018 Daniel Vrátil <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef AKONADI_AGENTCONFIGURATIONBASE_H
8 #define AKONADI_AGENTCONFIGURATIONBASE_H
9 
10 #include "agentconfigurationfactorybase.h"
11 #include "akonadicore_export.h"
12 
13 #include <KSharedConfig>
14 #include <QDialogButtonBox>
15 #include <QObject>
16 
17 class KAboutData;
18 
19 namespace Akonadi
20 {
21 /**
22  * @brief Base class for configuration UI for Akonadi agents
23  *
24  * Each agent that has a graphical configuration should subclass this class
25  * and create its configuration UI there.
26  *
27  * The subclass must reimplement load() and save() virtual methods which
28  * are called automatically. The load() method is called on start to initialize
29  * widgets (thus subclasses don't need to call it themselves) or when user
30  * clicks a "Reset" button. The save() method is called whenever user decides to
31  * save changes.
32  *
33  * Since each Akonadi agent instance has its own configuration file whose
34  * location and name is opaque to the implementation, config() method can be
35  * used to get access to the current configuration object.
36  *
37  * The widget will not run in the same process as the Akonadi agent, thus all
38  * communication with the resource (if needed) should be done over DBus. The
39  * identifier of the instance currently being configured is accessible from the
40  * identifier() method.
41  *
42  * There is no need to signal back to the resource when configuration is changed.
43  * When save() is called and the dialog is destroyed, Akonadi will automatically
44  * call AgentBase::reconfigure() in the respective Akonadi agent instance.
45  *
46  * It is guaranteed that only a single instance of the configuration dialog for
47  * given agent will be opened at the same time.
48  *
49  * Subclasses of ConfigurationBase must be registered as Akonadi plugins using
50  * AKONADI_AGENTCONFIG_FACTORY macro.
51  *
52  * The metadata JSON file then must contain the following values:
53  * @code
54  * {
55  * "X-Akonadi-PluginType": "AgentConfig",
56  * "X-Akonadi-Library": "exampleresourceconfig",
57  * "X-Akonadi-AgentConfig-Type": "akonadi_example_resource"
58  * }
59  * @endcode
60  *
61  * The @p X-Akonadi-Library value must match the name of the plugin binary without
62  * the (optional) "lib" prefix and file extension. The @p X-Akonadi-AgentConfig-Type
63  * value must match the name of the @p X-Akonadi-Identifier value from the agent's
64  * desktop file.
65  *
66  * The plugin binary should be installed into akonadi/config subdirectory in one
67  * of the paths search by QCoreApplication::libraryPaths().
68  */
69 
70 class AKONADICORE_EXPORT AgentConfigurationBase : public QObject
71 {
72  Q_OBJECT
73 public:
74  /**
75  * Creates a new AgentConfigurationBase objects.
76  *
77  * The @p parentWidget should be used as a parent widget for the configuration
78  * widgets.
79  *
80  * Subclasses must provide a constructor with this exact signature.
81  */
82  explicit AgentConfigurationBase(const KSharedConfigPtr &config, QWidget *parentWidget, const QVariantList &args);
83 
84  ~AgentConfigurationBase() override;
85 
86  /**
87  * Reimplement to load settings from the configuration object into widgets.
88  *
89  * @warning Always call the base class implementation at the beginning of
90  * your overridden method!
91  *
92  * @see config(), save()
93  */
94  virtual void load();
95 
96  /**
97  * Reimplement to save new settings into the configuration object.
98  *
99  * Return true if the configuration has been successfully saved and should
100  * be applied to the agent, return false otherwise.
101  *
102  * @warning Always remember call the base class implementation at the end
103  * of your overridden method!
104  *
105  * @see config(), load()
106  */
107  virtual bool save() const;
108 
109  /**
110  * Returns about data for the currently configured component.
111  *
112  * May return a null pointer.
113  */
114  KAboutData *aboutData() const;
115 
116  /**
117  * Reimplement to restore dialog size.
118  */
119  virtual QSize restoreDialogSize() const;
120 
121  /**
122  * Reimplement to save dialog size.
123  */
124  virtual void saveDialogSize(const QSize &size);
125 
126  virtual QDialogButtonBox::StandardButtons standardButtons() const;
127 
128 protected:
129  QWidget *parentWidget() const;
130 
131  /**
132  * Returns KConfig object belonging to the current Akonadi agent instance.
133  */
134  KSharedConfigPtr config() const;
135 
136  /**
137  * Returns identifier of the Akonadi agent instance currently being configured.
138  */
139  QString identifier() const;
140 
141  /**
142  * When KAboutData is provided the dialog will also contain KHelpMenu with
143  * access to user help etc.
144  */
145  void setKAboutData(const KAboutData &aboutData);
146 
147 Q_SIGNALS:
148  void enableOkButton(bool enabled);
149 
150 private:
151  class Private;
152  friend class Private;
154 };
155 
156 } // namespace
157 
158 #endif // AKONADI_AGENTCONFIGURATIONBASE_H
Base class for configuration UI for Akonadi agents.
typedef StandardButtons
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Mar 4 2021 23:18:09 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.