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 | |
29 | class KCompletion; |
30 | class KConfigGroup; |
31 | |
32 | namespace Plasma |
33 | { |
34 | |
35 | class QueryMatch; |
36 | class AbstractRunner; |
37 | class 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 | */ |
46 | class 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 | |
261 | Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::RunnerContext::Types) |
262 | |
263 | #endif |
264 | |