Akonadi

agentconfigurationbase.h
1/*
2 SPDX-FileCopyrightText: 2018 Daniel Vrátil <dvratil@kde.org>
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
18class KAboutData;
19
20namespace Akonadi
21{
22class 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
73class AKONADICORE_EXPORT AgentConfigurationBase : public QObject
74{
75 Q_OBJECT
76public:
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 struct ActivitySettings {
132 bool enabled = false;
133 QStringList activities;
134 };
135
136 /**
137 * @brief saveActivitiesSettings
138 * @param activities
139 * save activities settings
140 */
141 void saveActivitiesSettings(const ActivitySettings &activities) const;
142
143 /**
144 * @brief restoreActivitiesSettings
145 * @return activities settings
146 */
147 [[nodiscard]] ActivitySettings restoreActivitiesSettings() const;
148
149protected:
150 QWidget *parentWidget() const;
151
152 /**
153 * Returns KConfig object belonging to the current Akonadi agent instance.
154 */
155 KSharedConfigPtr config() const;
156
157 /**
158 * Returns identifier of the Akonadi agent instance currently being configured.
159 */
160 [[nodiscard]] QString identifier() const;
161
162 /**
163 * When KAboutData is provided the dialog will also contain KHelpMenu with
164 * access to user help etc.
165 */
166 void setKAboutData(const KAboutData &aboutData);
167
168Q_SIGNALS:
169 void enableOkButton(bool enabled);
170
171private:
172 friend class AgentConfigurationBasePrivate;
173 std::unique_ptr<AgentConfigurationBasePrivate> const d;
174};
175
176} // namespace
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-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:01:42 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.