1/*
2 SPDX-FileCopyrightText: 2006 Aaron Seigo <aseigo@kde.org>
3 SPDX-FileCopyrightText: 2007 Ryan P. Bitanga <ryan.bitanga@gmail.com>
4 SPDX-FileCopyrightText: 2008 Jordi Polo <mumismo@gmail.com>
5 SPDX-FileCopyrightText: 2023 Alexander Lohnau <alexander.lohnauŋmx.de>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9
10#ifndef KRUNNER_RUNNERMANAGER_H
11#define KRUNNER_RUNNERMANAGER_H
12
13#include <QList>
14#include <QObject>
15
16#include <KPluginMetaData>
17
18#include "abstractrunner.h"
19#include "action.h"
20#include "krunner_export.h"
21#include <memory>
22
23class KConfigGroup;
24namespace KRunner
25{
26class AbstractRunnerTest;
27}
28
29namespace KRunner
30{
31class QueryMatch;
32class AbstractRunner;
33class RunnerContext;
34class RunnerManagerPrivate;
35
36/*!
37 * \class KRunner::RunnerManager
38 * \inheaderfile KRunner/RunnerManager
39 * \inmodule KRunner
40 *
41 * \brief The RunnerManager class decides what installed runners are runnable,
42 * and their ratings. It is the main proxy to the runners.
43 */
44class KRUNNER_EXPORT RunnerManager : public QObject
45{
46 Q_OBJECT
47
48 /*!
49 * \property KRunner::RunnerManager::history
50 */
51 Q_PROPERTY(QStringList history READ history)
52
53 /*!
54 * \property KRunner::RunnerManager::querying
55 */
56 Q_PROPERTY(bool querying READ querying NOTIFY queryingChanged)
57
58 /*!
59 * \property KRunner::RunnerManager::historyEnabled
60 */
61 Q_PROPERTY(bool historyEnabled READ historyEnabled WRITE setHistoryEnabled NOTIFY historyEnabledChanged)
62
63public:
64 /*!
65 * Constructs a RunnerManager with the given parameters
66 *
67 * \a configurationGroup Config group used for reading enabled plugins
68 *
69 * \a stateGroup Config group used for storing history
70 *
71 * \since 6.0
72 */
73 explicit RunnerManager(const KConfigGroup &pluginConfigGroup, const KConfigGroup &stateGroup, QObject *parent);
74
75 /*!
76 * Constructs a RunnerManager using the default locations for state/plugin config
77 */
78 explicit RunnerManager(QObject *parent = nullptr);
79 ~RunnerManager() override;
80
81 /*!
82 * Finds and returns a loaded runner or a nullptr
83 *
84 * \a pluginId the name of the runner plugin
85 *
86 * Returns Pointer to the runner
87 */
88 AbstractRunner *runner(const QString &pluginId) const;
89
90 /*!
91 * Returns the list of all currently loaded runners
92 */
93 QList<AbstractRunner *> runners() const;
94
95 /*!
96 * Retrieves the current context
97 *
98 * Returns pointer to the current context
99 */
100 RunnerContext *searchContext() const;
101
102 /*!
103 * Retrieves all available matches found so far for the previously launched query
104 */
105 QList<QueryMatch> matches() const;
106
107 /*!
108 * Runs a given match. This also respects the extra handling for the InformationalMatch.
109 *
110 * This also handles the history automatically
111 *
112 * \a match the match to be executed
113 *
114 * \a selectedAction the action returned by QueryMatch::actions that has been selected by the user, nullptr if none
115 *
116 * Returns if the RunnerWindow should close
117 *
118 * \since 6.0
119 */
120 bool run(const QueryMatch &match, const KRunner::Action &action = {});
121
122 /*!
123 * Returns the current query term set in launchQuery
124 */
125 QString query() const;
126
127 /*!
128 * Returns History of this runner for the current activity. If the RunnerManager is not history
129 * aware the global entries will be returned.
130 * \since 5.78
131 */
132 QStringList history() const;
133
134 /*!
135 * Delete the given index from the history.
136 *
137 * \a historyEntry
138 * \since 5.78
139 */
140 Q_INVOKABLE void removeFromHistory(int index);
141
142 /*!
143 * Get the suggested history entry for the typed query. If no entry is found an empty string is returned.
144 *
145 * \a typedQuery
146 *
147 * Returns completion for typedQuery
148 * \since 5.78
149 */
150 Q_INVOKABLE QString getHistorySuggestion(const QString &typedQuery) const;
151
152 /*!
153 * If history completion is enabled, the default value is true.
154 * \since 5.78
155 */
156 bool historyEnabled();
157
158 /*!
159 * If the RunnerManager is currently querying
160 * \since 6.7
161 */
162 bool querying() const;
163
164 /*!
165 * Enables/disabled the history feature for the RunnerManager instance.
166 * The value will not be persisted and is only kept during the object's lifetime.
167 *
168 * \since 6.0
169 */
170 void setHistoryEnabled(bool enabled);
171
172 /*!
173 * Causes a reload of the current configuration
174 *
175 * This gets called automatically when the config in the KCM is saved
176 */
177 void reloadConfiguration();
178
179 /*!
180 * Sets a whitelist for the plugins that can be loaded by this manager.
181 *
182 * Runners that are disabled through the config will not be loaded.
183 *
184 * \a plugins the plugin names of allowed runners
185 */
186 void setAllowedRunners(const QStringList &runners);
187
188 /*!
189 * Attempts to add the AbstractRunner plugin represented
190 * by the plugin info passed in. Usually one can simply let
191 * the configuration of plugins handle loading Runner plugins,
192 * but in cases where specific runners should be loaded this
193 * allows for that to take place
194 *
195 * \note Consider using setAllowedRunners in case you want to only allow specific runners
196 *
197 * \a pluginMetaData the metaData to use to load the plugin
198 *
199 * Returns the loaded runner or nullptr
200 */
201 AbstractRunner *loadRunner(const KPluginMetaData &pluginMetaData);
202
203 /*!
204 * Returns mime data of the specified match
205 */
206 QMimeData *mimeDataForMatch(const QueryMatch &match) const;
207
208 /*!
209 * Returns metadata list of all known Runner plugins
210 * \since 5.72
211 */
212 static QList<KPluginMetaData> runnerMetaDataList();
213
214public Q_SLOTS:
215 /*!
216 * Call this method when the runners should be prepared for a query session.
217 * Call matchSessionComplete when the query session is finished for the time
218 * being.
219 * \sa matchSessionComplete
220 */
221 void setupMatchSession();
222
223 /*!
224 * Call this method when the query session is finished for the time
225 * being.
226 * \sa prepareForMatchSession
227 */
228 void matchSessionComplete();
229
230 /*!
231 * Launch a query, this will create threads and return immediately.
232 * When the information will be available can be known using the
233 * matchesChanged signal.
234 *
235 * \a term the term we want to find matches for
236 *
237 * \a runnerId optional, if only one specific runner is to be used;
238 * providing an id will put the manager into single runner mode
239 */
240 void launchQuery(const QString &term, const QString &runnerId = QString());
241
242 /*!
243 * Reset the current data and stops the query
244 */
245 void reset();
246
247 /*!
248 * Set the environment identifier for recording history and launch counts
249 * \internal
250 * \since 6.0
251 */
252 Q_INVOKABLE void setHistoryEnvironmentIdentifier(const QString &identifier);
253
254Q_SIGNALS:
255 /*!
256 * Emitted each time a new match is added to the list
257 */
258 void matchesChanged(const QList<KRunner::QueryMatch> &matches);
259
260 /*!
261 * Emitted when the launchQuery finish
262 */
263 void queryFinished();
264
265 /*!
266 * Emitted when the querying status has changed
267 * \since 6.7
268 */
269
270 void queryingChanged();
271
272 /*!
273 * Put the given search term in the KRunner search field
274 *
275 * \a term The term that should be displayed
276 *
277 * \a cursorPosition Where the cursor should be positioned
278 * \since 6.0
279 */
280 void requestUpdateQueryString(const QString &term, int cursorPosition);
281
282 /*!
283 * \sa historyEnabled
284 * \since 5.78
285 */
286 void historyEnabledChanged();
287
288private:
289 // exported for dbusrunnertest
290 KPluginMetaData convertDBusRunnerToJson(const QString &filename) const;
291 KRUNNER_NO_EXPORT Q_INVOKABLE void onMatchesChanged();
292
293 std::unique_ptr<RunnerManagerPrivate> d;
294
295 friend class RunnerManagerPrivate;
296 friend AbstractRunnerTest;
297 friend AbstractRunner;
298};
299
300}
301#endif
302

source code of krunner/src/runnermanager.h