1/*
2 * Copyright 2006-2007 Aaron Seigo <aseigo@kde.org>
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Library General Public License as
6 * published by the Free Software Foundation; either version 2, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details
13 *
14 * You should have received a copy of the GNU Library General Public
15 * License along with this program; if not, write to the
16 * Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 */
19
20#ifndef PLASMA_RUNNERCONTEXT_H
21#define PLASMA_RUNNERCONTEXT_H
22
23#include <QtCore/QList>
24#include <QtCore/QObject>
25#include <QtCore/QSharedDataPointer>
26
27#include <plasma/plasma_export.h>
28
29class KCompletion;
30class KConfigGroup;
31
32namespace Plasma
33{
34
35class QueryMatch;
36class AbstractRunner;
37class RunnerContextPrivate;
38
39/**
40 * @class RunnerContext plasma/runnercontext.h <Plasma/RunnerContext>
41 *
42 * @short The RunnerContext class provides information related to a search,
43 * including the search term, metadata on the search term and collected
44 * matches.
45 */
46class PLASMA_EXPORT RunnerContext : public QObject
47{
48 Q_OBJECT
49
50 public:
51 enum Type {
52 None = 0,
53 UnknownType = 1,
54 Directory = 2,
55 File = 4,
56 NetworkLocation = 8,
57 Executable = 16,
58 ShellCommand = 32,
59 Help = 64,
60 FileSystem = Directory | File | Executable | ShellCommand
61 };
62
63 Q_DECLARE_FLAGS(Types, Type)
64
65 explicit RunnerContext(QObject *parent = 0);
66
67 /**
68 * Copy constructor
69 */
70 RunnerContext(RunnerContext &other, QObject *parent = 0);
71
72 /**
73 * Assignment operator
74 * @since 4.4
75 */
76 RunnerContext &operator=(const RunnerContext &other);
77
78 ~RunnerContext();
79
80 /**
81 * Resets the search term for this object.
82 * This removes all current matches in the process and
83 * turns off single runner query mode.
84 */
85 void reset();
86
87 /**
88 * Sets the query term for this object and attempts to determine
89 * the type of the search.
90 */
91 void setQuery(const QString &term);
92
93 /**
94 * @return the current search query term.
95 */
96 QString query() const;
97
98 /**
99 * The type of item the search term might refer to.
100 * @see Type
101 */
102 Type type() const;
103
104 /**
105 * The mimetype that the search term refers to, if discoverable.
106 *
107 * @return QString() if the mimetype can not be determined, otherwise
108 * the mimetype of the object being referred to by the search
109 * string.
110 */
111 QString mimeType() const;
112
113 /**
114 * @returns true if this context is no longer valid and therefore
115 * matching using it should abort. Most useful as an optimization technique
116 * inside of AbstractRunner subclasses in the match method, e.g.:
117 *
118 * while (.. a possibly large iteration) {
119 * if (!context.isValid()) {
120 * return;
121 * }
122 *
123 * ... some processing ...
124 * }
125 *
126 * While not required to be used within runners, it provies a nice way
127 * to avoid unnecessary processing in runners that may run for an extended
128 * period (as measured in 10s of ms) and therefore improve the user experience.
129 * @since 4.2.3
130 */
131 bool isValid() const;
132
133 /**
134 * Appends lists of matches to the list of matches.
135 *
136 * This method is thread safe and causes the matchesChanged() signal to be emitted.
137 *
138 * @return true if matches were added, false if matches were e.g. outdated
139 */
140 // trueg: what do we need the term for? It is stored in the context anyway! Plus: matches() does not have a term parameter!
141 // plus: it is Q_UNUSED
142 bool addMatches(const QString &term, const QList<QueryMatch> &matches);
143
144 /**
145 * Appends a match to the existing list of matches.
146 *
147 * If you are going to be adding multiple matches, use addMatches instead.
148 *
149 * @param term the search term that this match was generated for.
150 * @param match the match to add
151 *
152 * @return true if the match was added, false otherwise.
153 */
154 // trueg: what do we need the term for? It is stored in the context anyway! Plus: matches() does not have a term parameter!
155 // plus: it is Q_UNUSED
156 bool addMatch(const QString &term, const QueryMatch &match);
157
158 /**
159 * Removes a match from the existing list of matches.
160 *
161 * If you are going to be removing multiple matches, use removeMatches instead.
162 *
163 * @param matchId the id of match to remove
164 *
165 * @return true if the match was removed, false otherwise.
166 * @since 4.4
167 */
168 bool removeMatch(const QString matchId);
169
170 /**
171 * Removes lists of matches from the existing list of matches.
172 *
173 * This method is thread safe and causes the matchesChanged() signal to be emitted.
174 *
175 * @param matchIdList the list of matches id to remove
176 *
177 * @return true if at least one match was removed, false otherwise.
178 * @since 4.4
179 */
180 bool removeMatches(const QStringList matchIdList);
181
182 /**
183 * Removes lists of matches from a given AbstractRunner
184 *
185 * This method is thread safe and causes the matchesChanged() signal to be emitted.
186 *
187 * @param runner the AbstractRunner from which to remove matches
188 *
189 * @return true if at least one match was removed, false otherwise.
190 * @since 4.10
191 */
192 bool removeMatches(AbstractRunner *runner);
193
194 /**
195 * Retrieves all available matches for the current search term.
196 *
197 * @return a list of matches
198 */
199 QList<QueryMatch> matches() const;
200
201 /**
202 * Retrieves a match by id.
203 *
204 * @param id the id of the match to return
205 * @return the match associated with this id, or an invalid QueryMatch object
206 * if the id does not eixst
207 */
208 QueryMatch match(const QString &id) const;
209
210 /**
211 * Sets single runner query mode. Note that a call to reset() will
212 * turn off single runner query mode.
213 *
214 * @see reset()
215 * @since 4.4
216 */
217 void setSingleRunnerQueryMode(bool enabled);
218
219 /**
220 * @return true if the current query is a single runner query
221 * @since 4.4
222 */
223 bool singleRunnerQueryMode() const;
224
225 /**
226 * Sets the launch counts for the associated match ids
227 *
228 * If a runner adds a match to this context, the context will check if the
229 * match id has been launched before and increase the matches relevance
230 * correspondingly. In this manner, any front end can implement adaptive search
231 * by sorting items according to relevance.
232 *
233 * @param config the config group where launch data was stored
234 */
235 void restore(const KConfigGroup &config);
236
237 /**
238 * @param config the config group where launch data should be stored
239 */
240 void save(KConfigGroup &config);
241
242 /**
243 * Run a match using the information from this context
244 *
245 * The context will also keep track of the number of times the match was
246 * launched to sort future matches according to user habits
247 *
248 * @param match the match to run
249 */
250 void run(const QueryMatch &match);
251
252 Q_SIGNALS:
253 void matchesChanged();
254
255 private:
256 QExplicitlySharedDataPointer<RunnerContextPrivate> d;
257};
258
259}
260
261Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::RunnerContext::Types)
262
263#endif
264