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 kpluginmodel.h KPluginModel
24 * A model that provides a list of available plugins and allows to disable/enable them.
25 *
26 * Plugins need to define the @c X-KDE-ConfigModule property for their config modules to be found.
27 * The value for this property is the namespace and file name of the KCM for the plugin.
28 * An example value is "kf6/krunner/kcms/kcm_krunner_charrunner", "kf6/krunner/kcms" is the namespace
29 * and "kcm_krunner_charrunner" the file name. The loaded KCMs don't need any embedded JSON metadata.
30 *
31 * @see KPluginWidget
32 *
33 * @since 5.94
34 */
35class KCMUTILSCORE_EXPORT KPluginModel : public QAbstractListModel
36{
37 Q_OBJECT
38
39public:
40 enum Roles {
41 NameRole = Qt::DisplayRole,
42 IconRole = Qt::DecorationRole,
43 EnabledRole = Qt::CheckStateRole,
44 DescriptionRole = Qt::UserRole + 1,
45 IsChangeableRole,
46 MetaDataRole,
47 ConfigRole,
48 IdRole,
49 EnabledByDefaultRole,
50 SortableRole, /// @internal
51 };
52
53 explicit KPluginModel(QObject *parent = nullptr);
54 ~KPluginModel() override;
55
56 QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
57 bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override;
58 int rowCount(const QModelIndex &parent = QModelIndex()) const override;
59 QHash<int, QByteArray> roleNames() const override;
60
61 bool moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild) override;
62
63 /**
64 * Append plugins to the model. This will not replace existing entries.
65 *
66 * @param plugins the plugins to be added.
67 * @param categoryLabel a user-visible label for the section the plugins are added to.
68 *
69 */
70 void addPlugins(const QList<KPluginMetaData> &plugins, const QString &categoryLabel);
71
72 /**
73 * Add plugins that should not be sorted automatically based on their name
74 * This is useful in case your app has a custom sorting mechanism or implements reordering of plugins
75 *
76 * @since 6.0
77 */
78 void addUnsortablePlugins(const QList<KPluginMetaData> &plugins, const QString &categoryLabel);
79
80 /// @since 6.0
81 void removePlugin(const KPluginMetaData &data);
82
83 /**
84 * Removes all plugins.
85 */
86 void clear();
87
88 /**
89 * Set the KConfigGroup that is used to load/save the enabled state.
90 */
91 void setConfig(const KConfigGroup &config);
92
93 /**
94 * Save the enabled state of the plugins to the config group set by @ref setConfig.
95 */
96 void save();
97
98 /**
99 * Load the enabled state of the plugins from the config group set by @ref setConfig.
100 */
101 void load();
102
103 /**
104 * Reset the enabled state of the plugins to its defaults.
105 */
106 void defaults();
107
108 /**
109 * Whether or not there are unsaved changes to the enabled state of the plugins.
110 */
111 bool isSaveNeeded();
112
113 /**
114 * Returns the KPluginMetaData object of the plugin's config module. If no plugin is found or the plugin does not have a config, the resulting
115 * KPluginMetaData object will be invalid.
116 * @since 5.94
117 */
118 KPluginMetaData findConfigForPluginId(const QString &pluginId) const;
119
120 /**
121 * Emitted when the enabled state matches the default changes.
122 *
123 * @see defaults
124 */
125 Q_SIGNAL void defaulted(bool isDefaulted);
126
127 /**
128 * Emitted when @ref isSaveNeeded is changed.
129 */
130 Q_SIGNAL void isSaveNeededChanged();
131
132private:
133 const std::unique_ptr<KPluginModelPrivate> d;
134 friend class KPluginProxyModel;
135 QStringList getOrderedCategoryLabels();
136};
137#endif
138

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