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

source code of krunner/src/runnermanager.h