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

source code of krunner/src/runnermanager.h