1/*
2 SPDX-FileCopyrightText: 2021 Nicolas Fella <nicolas.fella@gmx.de>
3 SPDX-FileCopyrightText: 2021 Alexander Lohnau <alexander.lohnau@gmx.de>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KPLUGINMODEL_H
9#define KPLUGINMODEL_H
10
11#include "kcmutilscore_export.h"
12
13#include <QAbstractListModel>
14#include <QList>
15
16#include <KPluginMetaData>
17#include <memory>
18
19class KConfigGroup;
20class KPluginModelPrivate;
21
22/*!
23 * \class KPluginModel
24 * \inmodule KCMUtilsCore
25 * \brief A model that provides a list of available plugins and allows to disable/enable them.
26 *
27 * Plugins need to define the \c X-KDE-ConfigModule property for their config modules to be found.
28 * The value for this property is the namespace and file name of the KCM for the plugin.
29 *
30 * An example value is "kf6/krunner/kcms/kcm_krunner_charrunner", "kf6/krunner/kcms" is the namespace
31 * and "kcm_krunner_charrunner" the file name. The loaded KCMs don't need any embedded JSON metadata.
32 *
33 * \sa KPluginWidget
34 *
35 * \since 5.94
36 */
37class KCMUTILSCORE_EXPORT KPluginModel : public QAbstractListModel
38{
39 Q_OBJECT
40
41public:
42 /*!
43 * \enum KPluginModel::Roles
44 *
45 * \value NameRole
46 * \value IconRole
47 * \value EnabledRole
48 * \value DescriptionRole
49 * \value IsChangeableRole
50 * \value MetaDataRole
51 * \value ConfigRole
52 * \value IdRole
53 * \value EnabledByDefaultRole
54 * \value SortableRole
55 */
56 enum Roles {
57 NameRole = Qt::DisplayRole,
58 IconRole = Qt::DecorationRole,
59 EnabledRole = Qt::CheckStateRole,
60 DescriptionRole = Qt::UserRole + 1,
61 IsChangeableRole,
62 MetaDataRole,
63 ConfigRole,
64 IdRole,
65 EnabledByDefaultRole,
66 SortableRole,
67 };
68
69 /*!
70 *
71 */
72 explicit KPluginModel(QObject *parent = nullptr);
73 ~KPluginModel() override;
74
75 QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
76 bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override;
77 int rowCount(const QModelIndex &parent = QModelIndex()) const override;
78 QHash<int, QByteArray> roleNames() const override;
79
80 bool moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild) override;
81
82 /*!
83 * \brief Appends \a plugins to the model.
84 *
85 * This will not replace existing entries.
86 *
87 * \a plugins The plugins to be added.
88 *
89 * \a categoryLabel A user-visible label for the section the plugins are added to.
90 */
91 void addPlugins(const QList<KPluginMetaData> &plugins, const QString &categoryLabel);
92
93 /*!
94 * \brief Adds \a plugins that should not be sorted automatically based on their name.
95 *
96 * This is useful in case your app has a custom sorting mechanism or implements reordering of plugins.
97 *
98 * \a plugins The plugins to be added.
99 *
100 * \a categoryLabel A user-visible label for the section the plugins are added to.
101 *
102 * \since 6.0
103 */
104 void addUnsortablePlugins(const QList<KPluginMetaData> &plugins, const QString &categoryLabel);
105
106 /*!
107 * \brief Removes a plugin with the specified \a data.
108 * \since 6.0
109 */
110 void removePlugin(const KPluginMetaData &data);
111
112 /*!
113 * \brief Removes all plugins.
114 */
115 void clear();
116
117 /*!
118 * \brief Sets the KConfigGroup \a config that is used
119 * to load/save the enabled state.
120 */
121 void setConfig(const KConfigGroup &config);
122
123 /*!
124 * \brief Saves the enabled state of the plugins to the config group set by \l setConfig.
125 */
126 void save();
127
128 /*!
129 * \brief Loads the enabled state of the plugins from the config group set by \l setConfig.
130 */
131 void load();
132
133 /*!
134 * \brief Resets the enabled state of the plugins to its defaults.
135 */
136 void defaults();
137
138 /*!
139 * \brief Returns whether there are unsaved changes to the enabled state of the plugins.
140 */
141 bool isSaveNeeded();
142
143 /*!
144 * \brief Returns the KPluginMetaData object of the plugin's config module with the specified \a pluginId.
145 *
146 * If no plugin is found or the plugin does not have a config, the resulting
147 * KPluginMetaData object will be invalid.
148 * \since 5.94
149 */
150 KPluginMetaData findConfigForPluginId(const QString &pluginId) const;
151
152 /*!
153 * \brief Emitted when the enabled state \a isDefaulted, that is, it matches the default changes.
154 * \sa defaults
155 */
156 Q_SIGNAL void defaulted(bool isDefaulted);
157
158 /*!
159 * \brief Emitted when isSaveNeeded is changed.
160 */
161 Q_SIGNAL void isSaveNeededChanged();
162
163private:
164 const std::unique_ptr<KPluginModelPrivate> d;
165 friend class KPluginProxyModel;
166 QStringList getOrderedCategoryLabels();
167};
168#endif
169

source code of kcmutils/src/core/kpluginmodel.h