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 | |
31 | class KComponentData; |
32 | class 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/<instancename>/<plugindir> 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 | */ |
58 | class KCMUTILS_EXPORT KPluginSelector |
59 | : public QWidget |
60 | { |
61 | Q_OBJECT |
62 | |
63 | public: |
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/<instancename>/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 | |
213 | Q_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 | |
226 | private: |
227 | class Private; |
228 | Private * const d; |
229 | }; |
230 | |
231 | #endif |
232 | |