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 | |
28 | class QAction; |
29 | class QIcon; |
30 | class QString; |
31 | class QVariant; |
32 | class QWidget; |
33 | |
34 | namespace Plasma |
35 | { |
36 | |
37 | class RunnerContext; |
38 | class AbstractRunner; |
39 | class 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 | */ |
47 | class 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 | |