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 KRunner::RunnerContext
27 * \inheaderfile KRunner/RunnerContext
28 * \inmodule KRunner
29 *
30 * \brief The RunnerContext class provides information related to a search,
31 * including the search term and collected matches.
32 */
33class KRUNNER_EXPORT RunnerContext final
34{
35public:
36 /*!
37 *
38 */
39 explicit RunnerContext(RunnerManager *manager = nullptr);
40
41 RunnerContext(const RunnerContext &other);
42
43 RunnerContext &operator=(const RunnerContext &other);
44
45 ~RunnerContext();
46
47 /*!
48 * Sets the query term for this object and attempts to determine
49 * the type of the search.
50 */
51 void setQuery(const QString &term);
52
53 /*!
54 * Returns the current search query term.
55 */
56 QString query() const;
57
58 /*!
59 * Returnss true if this context is no longer valid and therefore
60 * matching using it should abort.
61 * While not required to be used within runners, it provides a nice way
62 * to avoid unnecessary processing in runners that may run for an extended
63 * period (as measured in 10s of ms) and therefore improve the user experience.
64 */
65 bool isValid() const;
66
67 /*!
68 * Appends lists of matches to the list of matches.
69 *
70 * \a matches the matches to add
71 *
72 * Returns 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 addMatches instead.
81 *
82 * \a match the match to add
83 *
84 * Returns true if the match was added, false otherwise.
85 */
86 bool addMatch(const QueryMatch &match);
87
88 /*!
89 * Retrieves all available matches for the current search term.
90 *
91 * Returns a list of matches
92 */
93 QList<QueryMatch> matches() const;
94
95 /*!
96 * Request that KRunner updates the query string and stasy open, even after running a match.
97 * This method is const so it can be called in a const context.
98 *
99 * \a text Text that will be displayed in the search field
100 *
101 * \a cursorPosition Position of the cursor, if this is different than the length of the text,
102 * the characters between the position and text will be selected
103 *
104 * \since 5.90
105 */
106 void requestQueryStringUpdate(const QString &text, int cursorPosition) const;
107
108 /*!
109 * Returns true if the current query is a single runner query
110 */
111 bool singleRunnerQueryMode() const;
112
113 /*!
114 * Set this to true in the AbstractRunner::run method to prevent the entry
115 * from being saved to the history.
116 * \since 5.90
117 */
118 void ignoreCurrentMatchForHistory() const;
119
120private:
121 KRUNNER_NO_EXPORT void increaseLaunchCount(const QueryMatch &match);
122 KRUNNER_NO_EXPORT QString requestedQueryString() const;
123 KRUNNER_NO_EXPORT int requestedCursorPosition() const;
124 KRUNNER_NO_EXPORT bool shouldIgnoreCurrentMatchForHistory() const;
125 // Sets single runner query mode. Note that a call to reset() will turn off single runner query mode.
126 KRUNNER_NO_EXPORT void setSingleRunnerQueryMode(bool enabled);
127
128 friend class RunnerManager;
129 friend class AbstractRunner;
130 friend class DBusRunner;
131 friend class RunnerManagerPrivate;
132
133 KRUNNER_NO_EXPORT void restore(const KConfigGroup &config);
134 KRUNNER_NO_EXPORT void save(KConfigGroup &config);
135 KRUNNER_NO_EXPORT void reset();
136 KRUNNER_NO_EXPORT void setJobStartTs(qint64 queryStartTs);
137 KRUNNER_NO_EXPORT QString runnerJobId(AbstractRunner *runner) const;
138
139 QExplicitlySharedDataPointer<RunnerContextPrivate> d;
140};
141}
142
143Q_DECLARE_METATYPE(KRunner::RunnerContext)
144#endif
145

source code of krunner/src/runnercontext.h