KRunner

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

KDE's Doxygen guidelines are available online.