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

KDE's Doxygen guidelines are available online.