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_QUERYMATCH_H
21#define PLASMA_QUERYMATCH_H
22
23#include <QtCore/QList>
24#include <QtCore/QSharedDataPointer>
25
26#include <plasma/plasma_export.h>
27
28class QAction;
29class QIcon;
30class QString;
31class QVariant;
32class QWidget;
33
34namespace Plasma
35{
36
37class RunnerContext;
38class AbstractRunner;
39class QueryMatchPrivate;
40
41/**
42 * @class QueryMatch plasma/querymatch.h <Plasma/QueryMatch>
43 *
44 * @short A match returned by an AbstractRunner in response to a given
45 * RunnerContext.
46 */
47class PLASMA_EXPORT QueryMatch
48{
49 public:
50 /**
51 * The type of match. Value is important here as it is used for sorting
52 */
53 enum Type {
54 NoMatch = 0, /**< Null match */
55 CompletionMatch = 10, /**< Possible completion for the data of the query */
56 PossibleMatch = 30, /**< Something that may match the query */
57 InformationalMatch = 50, /**< A purely informational, non-actionable match,
58 such as the answer to a question or calculation*/
59 HelperMatch = 70, /**< A match that represents an action not directly related
60 to activating the given search term, such as a search
61 in an external tool or a command learning trigger. Helper
62 matches tend to be generic to the query and should not
63 be autoactivated just because the user hits "Enter"
64 while typing. They must be explicitly selected to
65 be activated, but unlike InformationalMatch cause
66 an action to be triggered. */
67 ExactMatch = 100 /**< An exact match to the query */
68 };
69
70 /**
71 * Constructs a PossibleMatch associated with a given RunnerContext
72 * and runner.
73 *
74 * @param runner the runner this match belongs to
75 */
76 explicit QueryMatch(AbstractRunner *runner);
77
78 /**
79 * Copy constructor
80 */
81 QueryMatch(const QueryMatch &other);
82
83 ~QueryMatch();
84 QueryMatch &operator=(const QueryMatch &other);
85 bool operator==(const QueryMatch &other) const;
86 bool operator!=(const QueryMatch &other) const;
87 bool operator<(const QueryMatch &other) const;
88
89
90 /**
91 * @return the runner associated with this action
92 */
93 AbstractRunner *runner() const;
94
95 /**
96 * @return true if the match is valid and can therefore be run,
97 * an invalid match does not have an associated AbstractRunner
98 */
99 bool isValid() const;
100
101 /**
102 * Sets the type of match this action represents.
103 */
104 void setType(Type type);
105
106 /**
107 * The type of action this is. Defaults to PossibleMatch.
108 */
109 Type type() const;
110
111 /**
112 * Sets the relevance of this action for the search
113 * it was created for.
114 *
115 * @param relevance a number between 0 and 1.
116 */
117 void setRelevance(qreal relevance);
118
119 /**
120 * The relevance of this action to the search. By default,
121 * the relevance is 1.
122 *
123 * @return a number between 0 and 1
124 */
125 qreal relevance() const;
126
127 /**
128 * Requests this match to activae using the given context
129 *
130 * @param context the context to use in conjunction with this run
131 *
132 * @sa AbstractRunner::run
133 */
134 void run(const RunnerContext &context) const;
135
136 /**
137 * Sets data to be used internally by the associated
138 * AbstractRunner.
139 *
140 * When set, it is also used to form
141 * part of the id() for this match. If that is innapropriate
142 * as an id, the runner may generate its own id and set that
143 * with setId(const QString&) directly after calling setData
144 */
145 void setData(const QVariant &data);
146
147 /**
148 * @return the data associated with this match; usually runner-specific
149 */
150 QVariant data() const;
151
152 /**
153 * Sets the id for this match; useful if the id does not
154 * match data().toString(). The id must be unique to all
155 * matches from this runner, and should remain constant
156 * for the same query for best results.
157 *
158 * @param id the new identifying string to use to refer
159 * to this entry
160 */
161 void setId(const QString &id);
162
163 /**
164 * @ruetnr a string that can be used as an ID for this match,
165 * even between different queries. It is based in part
166 * on the source of the match (the AbstractRunner) and
167 * distinguishing information provided by the runner,
168 * ensuring global uniqueness as well as consistency
169 * between query matches.
170 */
171 QString id() const;
172
173 /**
174 * Sets the main title text for this match; should be short
175 * enough to fit nicely on one line in a user interface
176 *
177 * @param text the text to use as the title
178 */
179 void setText(const QString &text);
180
181 /**
182 * @return the title text for this match
183 */
184 QString text() const;
185
186 /**
187 * Sets the descriptive text for this match; can be longer
188 * than the main title text
189 *
190 * @param text the text to use as the description
191 */
192 void setSubtext(const QString &text);
193
194 /**
195 * @return the descriptive text for this match
196 */
197 QString subtext() const;
198
199 /**
200 * Sets the icon associated with this match
201 *
202 * @param icon the icon to show along with the match
203 */
204 void setIcon(const QIcon &icon);
205
206 /**
207 * @return the icon for this match
208 */
209 QIcon icon() const;
210
211 /**
212 * Sets whether or not this match can be activited
213 *
214 * @param enable true if the match is enabled and therefore runnable
215 */
216 void setEnabled(bool enable);
217
218 /**
219 * @return true if the match is enabled and therefore runnable, otherwise false
220 */
221 bool isEnabled() const;
222
223 /**
224 * The current action.
225 */
226 QAction* selectedAction() const;
227
228 /**
229 * Sets the selected action
230 */
231 void setSelectedAction(QAction *action);
232
233 /**
234 * @return true if this match can be configured before being run
235 * @since 4.3
236 */
237 bool hasConfigurationInterface() const;
238
239 /**
240 * If hasConfigurationInterface() returns true, this method may be called to get
241 * a widget displaying the options the user can interact with to modify
242 * the behaviour of what happens when the match is run.
243 *
244 * @param widget the parent of the options widgets.
245 * @since 4.3
246 */
247 void createConfigurationInterface(QWidget *parent);
248
249 private:
250 QSharedDataPointer<QueryMatchPrivate> d;
251};
252
253}
254
255#endif
256