1/*
2 SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <aseigo@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KRUNNER_RUNNERCONTEXT_H
8#define KRUNNER_RUNNERCONTEXT_H
9
10#include <QList>
11#include <QMetaType>
12#include <QSharedDataPointer>
13
14#include "krunner_export.h"
15
16class KConfigGroup;
17
18namespace KRunner
19{
20class RunnerManager;
21class QueryMatch;
22class AbstractRunner;
23class RunnerContextPrivate;
24
25/**
26 * @class RunnerContext runnercontext.h <KRunner/RunnerContext>
27 *
28 * @short The RunnerContext class provides information related to a search,
29 * including the search term and collected matches.
30 */
31class KRUNNER_EXPORT RunnerContext final
32{
33public:
34 explicit RunnerContext(RunnerManager *manager = nullptr);
35
36 /**
37 * Copy constructor
38 */
39 RunnerContext(const RunnerContext &other);
40
41 /**
42 * Assignment operator
43 */
44 RunnerContext &operator=(const RunnerContext &other);
45
46 ~RunnerContext();
47
48 /**
49 * Sets the query term for this object and attempts to determine
50 * the type of the search.
51 */
52 void setQuery(const QString &term);
53
54 /**
55 * @return the current search query term.
56 */
57 QString query() const;
58
59 /**
60 * @returns true if this context is no longer valid and therefore
61 * matching using it should abort.
62 * While not required to be used within runners, it provides a nice way
63 * to avoid unnecessary processing in runners that may run for an extended
64 * period (as measured in 10s of ms) and therefore improve the user experience.
65 */
66 bool isValid() const;
67
68 /**
69 * Appends lists of matches to the list of matches.
70 *
71 * @param matches the matches to add
72 * @return true if matches were added, false if matches were e.g. outdated
73 */
74 bool addMatches(const QList<QueryMatch> &matches);
75
76 /**
77 * Appends a match to the existing list of matches.
78 *
79 * If you are going to be adding multiple matches, it is
80 * more performant to use @see addMatches instead.
81 *
82 * @param match the match to add
83 * @return true if the match was added, false otherwise.
84 */
85 bool addMatch(const QueryMatch &match);
86
87 /**
88 * Retrieves all available matches for the current search term.
89 *
90 * @return a list of matches
91 */
92 QList<QueryMatch> matches() const;
93
94 /**
95 * Request that KRunner updates the query string and stasy open, even after running a match.
96 * This method is const so it can be called in a const context.
97 *
98 * @param text Text that will be displayed in the search field
99 * @param cursorPosition Position of the cursor, if this is different than the length of the text,
100 * the characters between the position and text will be selected
101 *
102 * @since 5.90
103 */
104 void requestQueryStringUpdate(const QString &text, int cursorPosition) const;
105
106 /**
107 * @return true if the current query is a single runner query
108 */
109 bool singleRunnerQueryMode() const;
110
111 /**
112 * Set this to true in the AbstractRunner::run method to prevent the entry
113 * from being saved to the history.
114 * @since 5.90
115 */
116 void ignoreCurrentMatchForHistory() const;
117
118private:
119 KRUNNER_NO_EXPORT void increaseLaunchCount(const QueryMatch &match);
120 KRUNNER_NO_EXPORT QString requestedQueryString() const;
121 KRUNNER_NO_EXPORT int requestedCursorPosition() const;
122 KRUNNER_NO_EXPORT bool shouldIgnoreCurrentMatchForHistory() const;
123 // Sets single runner query mode. Note that a call to reset() will turn off single runner query mode.
124 KRUNNER_NO_EXPORT void setSingleRunnerQueryMode(bool enabled);
125
126 friend class RunnerManager;
127 friend class AbstractRunner;
128 friend class DBusRunner;
129 friend class RunnerManagerPrivate;
130
131 KRUNNER_NO_EXPORT void restore(const KConfigGroup &config);
132 KRUNNER_NO_EXPORT void save(KConfigGroup &config);
133 KRUNNER_NO_EXPORT void reset();
134 KRUNNER_NO_EXPORT void setJobStartTs(qint64 queryStartTs);
135 KRUNNER_NO_EXPORT QString runnerJobId(AbstractRunner *runner) const;
136
137 QExplicitlySharedDataPointer<RunnerContextPrivate> d;
138};
139}
140
141Q_DECLARE_METATYPE(KRunner::RunnerContext)
142#endif
143

source code of krunner/src/runnercontext.h