KRunner

runnercontext.h
1 /*
2  SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef PLASMA_RUNNERCONTEXT_H
8 #define PLASMA_RUNNERCONTEXT_H
9 
10 #include <QList>
11 #include <QObject>
12 #include <QSharedDataPointer>
13 
14 #include "krunner_export.h"
15 
16 class KConfigGroup;
17 
18 namespace Plasma
19 {
20 class QueryMatch;
21 class AbstractRunner;
22 class RunnerContextPrivate;
23 
24 /**
25  * @class RunnerContext runnercontext.h <KRunner/RunnerContext>
26  *
27  * @short The RunnerContext class provides information related to a search,
28  * including the search term, metadata on the search term and collected
29  * matches.
30  */
31 class KRUNNER_EXPORT RunnerContext : public QObject
32 {
33  Q_OBJECT
34 
35 public:
36  enum Type {
37  None = 0,
38  UnknownType = 1,
39  Directory = 2,
40  File = 4,
41  NetworkLocation = 8,
42  Executable = 16,
43  ShellCommand = 32,
44  Help = 64,
45  FileSystem = Directory | File | Executable | ShellCommand,
46  };
47 
48  Q_DECLARE_FLAGS(Types, Type)
49 
50  explicit RunnerContext(QObject *parent = nullptr);
51 
52  /**
53  * Copy constructor
54  */
55  RunnerContext(RunnerContext &other, QObject *parent = nullptr);
56 
57  /**
58  * Assignment operator
59  * @since 4.4
60  */
61  RunnerContext &operator=(const RunnerContext &other);
62 
63  ~RunnerContext() override;
64 
65  /**
66  * Resets the search term for this object.
67  * This removes all current matches in the process and
68  * turns off single runner query mode.
69  */
70  void reset();
71 
72  /**
73  * Sets the query term for this object and attempts to determine
74  * the type of the search.
75  */
76  void setQuery(const QString &term);
77 
78  /**
79  * @return the current search query term.
80  */
81  QString query() const;
82 
83 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
84  /**
85  * The type of item the search term might refer to.
86  * @see Type
87  * @deprecated feature is deprecated. Do the checks manually inside of the match logic
88  */
89  KRUNNER_DEPRECATED_VERSION(5, 76, "feature is deprecated. Do the checks manually inside of the match logic")
90  Type type() const;
91 #endif
92 
93 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
94  /**
95  * A list of categories of which results should be returned.
96  * This list is typically populated from the AbstractRunner::categories
97  * function.
98  * @deprecated Since 5.76, feature is unused and not supported by most runners
99  */
100  KRUNNER_DEPRECATED_VERSION(5, 76, "feature is unused and not supported by most runners")
101  QStringList enabledCategories() const;
102 #endif
103 
104 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
105  /**
106  * Sets the list of enabled categories. Runners can use this list
107  * to optimize themselves by only returning results from the enabled
108  * categories
109  * @deprecated Since 5.76, feature is unused and not supported by most runners
110  */
111  KRUNNER_DEPRECATED_VERSION(5, 76, "feature is unused and not supported by most runners")
112  void setEnabledCategories(const QStringList &categories);
113 #endif
114 
115 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
116  /**
117  * The mimetype that the search term refers to, if discoverable.
118  *
119  * @return QString() if the mimetype can not be determined, otherwise
120  * the mimetype of the object being referred to by the search
121  * string.
122  * @deprecated feature is unused, determine the mime type manually if needed
123  */
124  KRUNNER_DEPRECATED_VERSION(5, 76, "feature is unused, determine the mime type manually if needed")
125  QString mimeType() const;
126 #endif
127 
128  /**
129  * @returns true if this context is no longer valid and therefore
130  * matching using it should abort. Most useful as an optimization technique
131  * inside of AbstractRunner subclasses in the match method, e.g.:
132  *
133  * while (.. a possibly large iteration) {
134  * if (!context.isValid()) {
135  * return;
136  * }
137  *
138  * ... some processing ...
139  * }
140  *
141  * While not required to be used within runners, it provides a nice way
142  * to avoid unnecessary processing in runners that may run for an extended
143  * period (as measured in 10s of ms) and therefore improve the user experience.
144  * @since 4.2.3
145  */
146  bool isValid() const;
147 
148  /**
149  * Appends lists of matches to the list of matches.
150  *
151  * @param matches the matches to add
152  * @return true if matches were added, false if matches were e.g. outdated
153  */
154  bool addMatches(const QList<QueryMatch> &matches);
155 
156  /**
157  * Appends a match to the existing list of matches.
158  *
159  * If you are going to be adding multiple matches, use @see addMatches instead.
160  *
161  * @param match the match to add
162  * @return true if the match was added, false otherwise.
163  */
164  bool addMatch(const QueryMatch &match);
165 
166 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
167  /**
168  * Removes a match from the existing list of matches.
169  *
170  * If you are going to be removing multiple matches, use removeMatches instead.
171  *
172  * @param matchId the id of match to remove
173  *
174  * @return true if the match was removed, false otherwise.
175  * @since 4.4
176  * @deprecated Since 5.81, feature is unused, aggregate and filter the matches before adding them to the runnercontext instead
177  */
178  KRUNNER_DEPRECATED_VERSION(5, 81, "feature is unused, aggregate and filter the matches before adding them to the runnercontext instead")
179  bool removeMatch(const QString matchId);
180 #endif
181 
182 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
183  /**
184  * Removes lists of matches from the existing list of matches.
185  *
186  * This method is thread safe and causes the matchesChanged() signal to be emitted.
187  *
188  * @param matchIdList the list of matches id to remove
189  *
190  * @return true if at least one match was removed, false otherwise.
191  * @since 4.4
192  * @deprecated Since 5.81, feature is unused, aggregate and filter the matches before adding them to the runnercontext instead
193  */
194  KRUNNER_DEPRECATED_VERSION(5, 81, "feature is unused, aggregate and filter the matches before adding them to the runnercontext instead")
195  bool removeMatches(const QStringList matchIdList);
196 #endif
197 
198 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
199  /**
200  * Removes lists of matches from a given AbstractRunner
201  *
202  * This method is thread safe and causes the matchesChanged() signal to be emitted.
203  *
204  * @param runner the AbstractRunner from which to remove matches
205  *
206  * @return true if at least one match was removed, false otherwise.
207  * @since 4.10
208  * @deprecated Since 5.81, feature is unused, aggregate and filter the matches before adding them to the runnercontext instead
209  */
210  KRUNNER_DEPRECATED_VERSION(5, 81, "feature is unused, aggregate and filter the matches before adding them to the runnercontext instead")
211  bool removeMatches(AbstractRunner *runner);
212 #endif
213 
214  /**
215  * Retrieves all available matches for the current search term.
216  *
217  * @return a list of matches
218  */
219  QList<QueryMatch> matches() const;
220 
221 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 79)
222  /**
223  * Retrieves a match by id.
224  *
225  * @param id the id of the match to return
226  * @return the match associated with this id, or an invalid QueryMatch object
227  * if the id does not exist
228  * @deprecated Since 5.79, deprecated due to lack of usage. Instead filter the matches manually based on the id
229  */
230  KRUNNER_DEPRECATED_VERSION(5, 79, "Deprecated due to lack of usage, instead filter the matches manually based on the id")
231  QueryMatch match(const QString &id) const;
232 #endif
233 
234  /**
235  * Request that KRunner updates the query string and stasy open, even after running a match.
236  * This method is const so it can be called in a const context.
237  *
238  * @param text Text that will be displayed in the search field
239  * @param cursorPosition Position of the cursor, if this is different than the length of the text,
240  * the characters between the position and text will be selected
241  *
242  * @since 5.90
243  */
244  void requestQueryStringUpdate(const QString &text, int cursorPosition) const;
245 
246  /**
247  * Sets single runner query mode. Note that a call to reset() will
248  * turn off single runner query mode.
249  *
250  * @note This method is considered internal. To set the single runner mode you should pass in a runnerId to @ref RunnerManager::launchQuery
251  * @see reset()
252  * @internal
253  * @since 4.4
254  */
255  // TODO KF6 Make private
256  void setSingleRunnerQueryMode(bool enabled);
257 
258  /**
259  * @return true if the current query is a single runner query
260  * @since 4.4
261  */
262  bool singleRunnerQueryMode() const;
263 
264  /**
265  * Set this to true in the AbstractRunner::run method to prevent the entry
266  * from being saved to the history.
267  * @since 5.90
268  */
269  void ignoreCurrentMatchForHistory() const;
270 
271  /**
272  * Sets the launch counts for the associated match ids
273  *
274  * If a runner adds a match to this context, the context will check if the
275  * match id has been launched before and increase the matches relevance
276  * correspondingly. In this manner, any front end can implement adaptive search
277  * by sorting items according to relevance.
278  *
279  * @param config the config group where launch data was stored
280  */
281  void restore(const KConfigGroup &config);
282 
283  /**
284  * @param config the config group where launch data should be stored
285  */
286  void save(KConfigGroup &config);
287 
288  /**
289  * Run a match using the information from this context
290  *
291  * The context will also keep track of the number of times the match was
292  * launched to sort future matches according to user habits
293  *
294  * @param match the match to run
295  */
296  void run(const QueryMatch &match);
297 
298 Q_SIGNALS:
299  void matchesChanged();
300 
301 private:
302  KRUNNER_NO_EXPORT QString requestedQueryString() const;
303  KRUNNER_NO_EXPORT int requestedCursorPosition() const;
304  KRUNNER_NO_EXPORT bool shouldIgnoreCurrentMatchForHistory() const;
305  friend class RunnerManager;
307 };
308 
309 Q_DECLARE_OPERATORS_FOR_FLAGS(RunnerContext::Types)
310 
311 }
312 
313 #endif
The RunnerManager class decides what installed runners are runnable, and their ratings....
Definition: runnermanager.h:46
A match returned by an AbstractRunner in response to a given RunnerContext.
Definition: querymatch.h:34
An abstract base class for Plasma Runner plugins.
KSharedConfigPtr config()
The RunnerContext class provides information related to a search, including the search term,...
Definition: runnercontext.h:31
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 2 2023 03:51:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.