1 | /* |
2 | * Copyright (C) 2006 Aaron Seigo <aseigo@kde.org> |
3 | * Copyright (C) 2007 Ryan P. Bitanga <ryan.bitanga@gmail.com> |
4 | * Copyright (C) 2008 Jordi Polo <mumismo@gmail.com> |
5 | * |
6 | * This program is free software; you can redistribute it and/or modify |
7 | * it under the terms of the GNU Library General Public License as |
8 | * published by the Free Software Foundation; either version 2, or |
9 | * (at your option) any later version. |
10 | * |
11 | * This program is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
14 | * GNU General Public License for more details |
15 | * |
16 | * You should have received a copy of the GNU Library General Public |
17 | * License along with this program; if not, write to the |
18 | * Free Software Foundation, Inc., |
19 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
20 | */ |
21 | |
22 | #ifndef PLASMA_RUNNERMANAGER_H |
23 | #define PLASMA_RUNNERMANAGER_H |
24 | |
25 | #include <QtCore/QList> |
26 | #include <QtCore/QObject> |
27 | |
28 | #include <kplugininfo.h> |
29 | |
30 | #include <plasma/plasma_export.h> |
31 | #include "abstractrunner.h" |
32 | |
33 | class QAction; |
34 | class KConfigGroup; |
35 | |
36 | namespace Plasma |
37 | { |
38 | class QueryMatch; |
39 | class AbstractRunner; |
40 | class RunnerContext; |
41 | class RunnerManagerPrivate; |
42 | |
43 | /** |
44 | * @class RunnerManager plasma/runnermanager.h <Plasma/RunnerManager> |
45 | * |
46 | * @short The RunnerManager class decides what installed runners are runnable, |
47 | * and their ratings. It is the main proxy to the runners. |
48 | */ |
49 | class PLASMA_EXPORT RunnerManager : public QObject |
50 | { |
51 | Q_OBJECT |
52 | |
53 | public: |
54 | explicit RunnerManager(QObject *parent=0); |
55 | explicit RunnerManager(KConfigGroup &config, QObject *parent=0); |
56 | ~RunnerManager(); |
57 | |
58 | /** |
59 | * Finds and returns a loaded runner or NULL |
60 | * @param name the name of the runner |
61 | * @return Pointer to the runner |
62 | */ |
63 | AbstractRunner *runner(const QString &name) const; |
64 | |
65 | /** |
66 | * @return the currently active "single mode" runner, or null if none |
67 | * @since 4.4 |
68 | */ |
69 | AbstractRunner *singleModeRunner() const; |
70 | |
71 | /** |
72 | * Puts the manager into "single runner" mode using the given |
73 | * runner; if the runner does not exist or can not be loaded then |
74 | * the single runner mode will not be started and singleModeRunner() |
75 | * will return NULL |
76 | * @param id the id of the runner to use |
77 | * @since 4.4 |
78 | */ |
79 | void setSingleModeRunnerId(const QString &id); |
80 | |
81 | /** |
82 | * @return the id of the runner to use in single mode |
83 | * @since 4.4 |
84 | */ |
85 | QString singleModeRunnerId() const; |
86 | |
87 | /** |
88 | * @return true if the manager is set to run in single runner mode |
89 | * @since 4.4 |
90 | */ |
91 | bool singleMode() const; |
92 | |
93 | /** |
94 | * Sets whether or not the manager is in single mode. |
95 | * |
96 | * @param singleMode true if the manager should be in single mode, false otherwise |
97 | * @since 4.4 |
98 | */ |
99 | void setSingleMode(bool singleMode); |
100 | |
101 | /** |
102 | * Returns the translated name of a runner |
103 | * @param id the id of the runner |
104 | * |
105 | * @since 4.4 |
106 | */ |
107 | QString runnerName(const QString &id) const; |
108 | |
109 | /** |
110 | * @return the list of all currently loaded runners |
111 | */ |
112 | QList<AbstractRunner *> runners() const; |
113 | |
114 | /** |
115 | * @return the names of all runners that advertise single query mode |
116 | * @since 4.4 |
117 | */ |
118 | QStringList singleModeAdvertisedRunnerIds() const; |
119 | |
120 | /** |
121 | * Retrieves the current context |
122 | * @return pointer to the current context |
123 | */ |
124 | RunnerContext *searchContext() const; |
125 | |
126 | /** |
127 | * Retrieves all available matches found so far for the previously launched query |
128 | * @return List of matches |
129 | */ |
130 | QList<QueryMatch> matches() const; |
131 | |
132 | /** |
133 | * Runs a given match |
134 | * @param match the match to be executed |
135 | */ |
136 | void run(const QueryMatch &match); |
137 | |
138 | /** |
139 | * Runs a given match |
140 | * @param id the id of the match to run |
141 | */ |
142 | void run(const QString &id); |
143 | |
144 | /** |
145 | * Retrieves the list of actions, if any, for a match |
146 | */ |
147 | QList<QAction*> actionsForMatch(const QueryMatch &match); |
148 | |
149 | /** |
150 | * @return the current query term |
151 | */ |
152 | QString query() const; |
153 | |
154 | /** |
155 | * Causes a reload of the current configuration |
156 | */ |
157 | void reloadConfiguration(); |
158 | |
159 | /** |
160 | * Sets a whitelist for the plugins that can be loaded |
161 | * |
162 | * @param plugins the plugin names of allowed runners |
163 | * @since 4.4 |
164 | */ |
165 | void setAllowedRunners(const QStringList &runners); |
166 | |
167 | /** |
168 | * Attempts to add the AbstractRunner plugin represented |
169 | * by the KService passed in. Usually one can simply let |
170 | * the configuration of plugins handle loading Runner plugins, |
171 | * but in cases where specific runners should be loaded this |
172 | * allows for that to take place |
173 | * |
174 | * @param service the service to use to load the plugin |
175 | * @since 4.5 |
176 | */ |
177 | void loadRunner(const KService::Ptr service); |
178 | |
179 | /** |
180 | * Attempts to add the AbstractRunner from a Plasma::Package on disk. |
181 | * Usually one can simply let the configuration of plugins |
182 | * handle loading Runner plugins, but in cases where specific |
183 | * runners should be loaded this allows for that to take place |
184 | * |
185 | * @param path the path to a Runner package to load |
186 | * @since 4.5 |
187 | */ |
188 | void loadRunner(const QString &path); |
189 | |
190 | /** |
191 | * @return the list of allowed plugins |
192 | * @since 4.4 |
193 | */ |
194 | QStringList allowedRunners() const; |
195 | |
196 | /** |
197 | * @return mime data of the specified match |
198 | * @since 4.5 |
199 | */ |
200 | QMimeData * mimeDataForMatch(const QueryMatch &match) const; |
201 | |
202 | /** |
203 | * @return mime data of the specified match |
204 | * @since 4.5 |
205 | */ |
206 | QMimeData * mimeDataForMatch(const QString &id) const; |
207 | |
208 | /** |
209 | * Returns a list of all known Runner implementations |
210 | * |
211 | * @param parentApp the application to filter applets on. Uses the |
212 | * X-KDE-ParentApp entry (if any) in the plugin info. |
213 | * The default value of QString() will result in a |
214 | * list containing only applets not specifically |
215 | * registered to an application. |
216 | * @return list of AbstractRunners |
217 | * @since 4.6 |
218 | **/ |
219 | static KPluginInfo::List listRunnerInfo(const QString &parentApp = QString()); |
220 | |
221 | public Q_SLOTS: |
222 | /** |
223 | * Call this method when the runners should be prepared for a query session. |
224 | * Call matchSessionComplete when the query session is finished for the time |
225 | * being. |
226 | * @since 4.4 |
227 | * @see matchSessionComplete |
228 | */ |
229 | void setupMatchSession(); |
230 | |
231 | /** |
232 | * Call this method when the query session is finished for the time |
233 | * being. |
234 | * @since 4.4 |
235 | * @see prepareForMatchSession |
236 | */ |
237 | void matchSessionComplete(); |
238 | |
239 | /** |
240 | * Launch a query, this will create threads and return inmediately. |
241 | * When the information will be available can be known using the |
242 | * matchesChanged signal. |
243 | * |
244 | * @param term the term we want to find matches for |
245 | * @param runnerId optional, if only one specific runner is to be used; |
246 | * providing an id will put the manager into single runner mode |
247 | */ |
248 | void launchQuery(const QString &term, const QString &runnerId); |
249 | |
250 | /** |
251 | * Convenience version of above |
252 | */ |
253 | void launchQuery(const QString &term); |
254 | |
255 | /** |
256 | * Execute a query, this method will only return when the query is executed |
257 | * This means that the method may be dangerous as it wait a variable amount |
258 | * of time for the runner to finish. |
259 | * The runner parameter is mandatory, to avoid launching unwanted runners. |
260 | * @param term the term we want to find matches for |
261 | * @param runner the runner we will use, it is mandatory |
262 | * @return 0 if nothing was launched, 1 if launched. |
263 | */ |
264 | bool execQuery(const QString &term, const QString &runnerName); |
265 | |
266 | /** |
267 | * Convenience version of above |
268 | */ |
269 | bool execQuery(const QString &term); |
270 | |
271 | /** |
272 | * Reset the current data and stops the query |
273 | */ |
274 | void reset(); |
275 | |
276 | Q_SIGNALS: |
277 | /** |
278 | * Emitted each time a new match is added to the list |
279 | */ |
280 | void matchesChanged(const QList<Plasma::QueryMatch> &matches); |
281 | |
282 | /** |
283 | * Emitted when the launchQuery finish |
284 | * @since 4.5 |
285 | */ |
286 | void queryFinished(); |
287 | |
288 | private: |
289 | Q_PRIVATE_SLOT(d, void scheduleMatchesChanged()) |
290 | Q_PRIVATE_SLOT(d, void matchesChanged()) |
291 | Q_PRIVATE_SLOT(d, void jobDone(ThreadWeaver::Job*)) |
292 | Q_PRIVATE_SLOT(d, void unblockJobs()) |
293 | Q_PRIVATE_SLOT(d, void runnerMatchingSuspended(bool)) |
294 | |
295 | RunnerManagerPrivate * const d; |
296 | |
297 | friend class RunnerManagerPrivate; |
298 | }; |
299 | |
300 | } |
301 | |
302 | #endif |
303 | |