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
33class QAction;
34class KConfigGroup;
35
36namespace 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 */
49class 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