1/**
2 * This file is part of the KDE project
3 * Copyright (C) 2007, 2006 Rafael Fernández López <ereslibre@kde.org>
4 * Copyright (C) 2002-2003 Matthias Kretz <kretz@kde.org>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License version 2 as published by the Free Software Foundation.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
14 *
15 * You should have received a copy of the GNU Library General Public License
16 * along with this library; see the file COPYING.LIB. If not, write to
17 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 * Boston, MA 02110-1301, USA.
19 */
20
21#ifndef KPLUGINSELECTOR_H
22#define KPLUGINSELECTOR_H
23
24#include <QtGui/QWidget>
25
26#include <QtCore/QList>
27
28#include <kcmutils_export.h>
29#include <ksharedconfig.h>
30
31class KComponentData;
32class KPluginInfo;
33
34
35/**
36 * @short A widget to select what plugins to load and configure the plugins.
37 *
38 * It shows the list of available plugins
39 *
40 * Since the user needs a way to know what a specific plugin does every plugin
41 * sould install a desktop file containing a name, comment and category field.
42 * The category is useful for applications that can use different kinds of
43 * plugins like a playlist, skin or visualization
44 *
45 * The location of these desktop files is the
46 * share/apps/&lt;instancename&gt;/&lt;plugindir&gt; directory. But if you need
47 * you may use a different directory
48 *
49 * You can add plugins from different KConfig[group], by just calling all times
50 * you want addPlugins method with the correct parameters
51 *
52 * Additionally, calls to constructor with same @p categoryName, will add new
53 * items to the same category, even if plugins are from different categories
54 *
55 * @author Matthias Kretz <kretz@kde.org>
56 * @author Rafael Fernández López <ereslibre@kde.org>
57 */
58class KCMUTILS_EXPORT KPluginSelector
59 : public QWidget
60{
61 Q_OBJECT
62
63public:
64 enum PluginLoadMethod {
65 ReadConfigFile = 0,
66 IgnoreConfigFile
67 };
68
69 /**
70 * Create a new KPluginSelector
71 */
72 KPluginSelector(QWidget *parent = 0);
73
74 /**
75 * Destructor
76 */
77 ~KPluginSelector();
78
79 /**
80 * Add a list of KParts plugins
81 *
82 * The information about the plugins will be loaded from the
83 * share/apps/&lt;instancename&gt;/kpartplugins directory
84 *
85 * @param componentName The name of the KComponentData of the plugin's parent.
86 * @param categoryName The translated name of the category. This is the
87 * name that is shown in the title. If the category
88 * did exist before because of another call to
89 * addPlugins, then they will be shown in that
90 * category. If @p categoryName is a new one, then
91 * a new category will be shown on the plugin window,
92 * and the list of plugins added to it
93 * @param categoryKey When you have different categories of KParts
94 * plugins you distinguish between the plugins using
95 * the Category key in the .desktop file. Use this
96 * parameter to select only those KParts plugins
97 * with the Category key == @p categoryKey. If
98 * @p categoryKey is not set the Category key is
99 * ignored and all plugins are shown. Not match case
100 * @param config The KConfig object that holds the state of the
101 * plugins being enabled or not. By default it should
102 * be componentData.config(). It is recommended to
103 * always pass a KConfig object if you use
104 * KSettings::PluginPage since you never know from where the
105 * page will be called (think global config app).
106 * For example KViewCanvas passes KConfig(
107 * "kviewcanvas" )
108 */
109 void addPlugins(const QString &componentName,
110 const QString &categoryName = QString(),
111 const QString &categoryKey = QString(),
112 KSharedConfig::Ptr config = KSharedConfig::Ptr());
113
114 /**
115 * Add a list of KParts plugins. Convenience method for the one above.
116 * If not set explicitly, @p config is set to componentData.config()
117 */
118 void addPlugins(const KComponentData &instance,
119 const QString &categoryName = QString(),
120 const QString &categoryKey = QString(),
121 const KSharedConfig::Ptr &config = KSharedConfig::Ptr());
122
123 /**
124 * Add a list of non-KParts plugins
125 *
126 * @param pluginInfoList A list of KPluginInfo objects containing the
127 * necessary information for the plugins you want to
128 * add to the list
129 * @param pluginLoadMethod If KPluginSelector will try to load the
130 * state of the plugin when loading the
131 * dialog from the configuration file or not.
132 * This is useful if for some reason you
133 * called the setPluginEnabled() for each plugin
134 * individually before loading the dialog, and
135 * don't want KPluginSelector to override them
136 * when loading
137 * @param categoryName The translated name of the category. This is the
138 * name that is shown in the title. If the category
139 * did exist before because of another call to
140 * addPlugins, then they will be shown in that
141 * category. If @p categoryName is a new one, then
142 * a new category will be shown on the plugin window,
143 * and the list of plugins added to it
144 * @param categoryKey When you have different categories of KParts
145 * plugins you distinguish between the plugins using
146 * the Category key in the .desktop file. Use this
147 * parameter to select only those KParts plugins
148 * with the Category key == @p categoryKey. If
149 * @p categoryKey is not set the Category key is
150 * ignored and all plugins are shown. Not match case
151 * @param config The KConfig object that holds the state of the
152 * plugins being enabled or not. By default it will
153 * use KGlobal::config(). It is recommended to
154 * always pass a KConfig object if you use
155 * KSettings::PluginPage since you never know from
156 * where the page will be called (think global
157 * config app). For example KViewCanvas passes
158 * KConfig("kviewcanvas")
159 *
160 * @note All plugins that were set a config group using setConfig() method
161 * will load and save their information from there. For those that
162 * weren't any config object, @p config will be used
163 */
164 void addPlugins(const QList<KPluginInfo> &pluginInfoList,
165 PluginLoadMethod pluginLoadMethod = ReadConfigFile,
166 const QString &categoryName = QString(),
167 const QString &categoryKey = QString(),
168 const KSharedConfig::Ptr &config = KSharedConfig::Ptr());
169
170 /**
171 * Load the state of the plugins (selected or not) from the KPluginInfo
172 * objects
173 */
174 void load();
175
176 /**
177 * Save the configuration
178 */
179 void save();
180
181 /**
182 * Change to applications defaults
183 * @see isDefault()
184 */
185 void defaults();
186
187 /**
188 * Returns true if the plugin selector does not have any changes to application defaults
189 * @see defaults()
190 * @since 4.3
191 */
192 bool isDefault() const;
193
194 /**
195 * Updates plugins state (enabled or not)
196 *
197 * This method won't save anything on any configuration file. It will just
198 * be useful if you added plugins with the method:
199 *
200 * \code
201 * void addPlugins(const QList<KPluginInfo> &pluginInfoList,
202 * const QString &categoryName = QString(),
203 * const QString &categoryKey = QString(),
204 * const KSharedConfig::Ptr &config = KSharedConfig::Ptr());
205 * \endcode
206 *
207 * To sum up, this method will update your plugins state depending if plugins
208 * are ticked or not on the KPluginSelector dialog, without saving anything
209 * anywhere
210 */
211 void updatePluginsState();
212
213Q_SIGNALS:
214 /**
215 * Tells you whether the configuration is changed or not.
216 */
217 void changed(bool hasChanged);
218
219 /**
220 * Emitted after the config of an embedded KCM has been saved. The
221 * argument is the name of the parent component that needs to reload
222 * its config
223 */
224 void configCommitted(const QByteArray &componentName);
225
226private:
227 class Private;
228 Private * const d;
229};
230
231#endif
232