1 | /* |
2 | SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <aseigo@kde.org> |
3 | SPDX-FileCopyrightText: 2023 Alexander Lohnau <alexander.lohnau@gmx.de> |
4 | |
5 | SPDX-License-Identifier: LGPL-2.0-or-later |
6 | */ |
7 | |
8 | #ifndef KRUNNER_QUERYMATCH_H |
9 | #define KRUNNER_QUERYMATCH_H |
10 | |
11 | #include <QList> |
12 | #include <QSharedDataPointer> |
13 | #include <QUrl> |
14 | |
15 | #include "krunner_export.h" |
16 | |
17 | class QIcon; |
18 | class QVariant; |
19 | |
20 | namespace KRunner |
21 | { |
22 | class Action; |
23 | class AbstractRunner; |
24 | class QueryMatchPrivate; |
25 | |
26 | /** |
27 | * @class QueryMatch querymatch.h <KRunner/QueryMatch> |
28 | * |
29 | * @short A match returned by an AbstractRunner in response to a given RunnerContext. |
30 | */ |
31 | class KRUNNER_EXPORT QueryMatch |
32 | { |
33 | public: |
34 | /** |
35 | * The type of match. Value is important here as it is used for sorting |
36 | */ |
37 | enum Type { |
38 | NoMatch = 0, /**< Null match */ |
39 | CompletionMatch = 10, /**< Possible completion for the data of the query */ |
40 | PossibleMatch = 30, /**< Something that may match the query */ |
41 | /** |
42 | * A match that represents an action not directly related |
43 | * to activating the given search term, such as a search |
44 | * in an external tool or a command learning trigger. Helper |
45 | * matches tend to be generic to the query and should not |
46 | * be autoactivated just because the user hits "Enter" |
47 | * while typing. |
48 | */ |
49 | HelperMatch = 70, |
50 | ExactMatch = 100, /**< An exact match to the query */ |
51 | }; |
52 | |
53 | /** |
54 | * Constructs a PossibleMatch associated with a given RunnerContext |
55 | * and runner. |
56 | * |
57 | * @param runner the runner this match belongs to |
58 | */ |
59 | explicit QueryMatch(AbstractRunner *runner = nullptr); |
60 | |
61 | /** |
62 | * Copy constructor |
63 | */ |
64 | QueryMatch(const QueryMatch &other); |
65 | |
66 | ~QueryMatch(); |
67 | QueryMatch &operator=(const QueryMatch &other); |
68 | bool operator==(const QueryMatch &other) const; |
69 | bool operator!=(const QueryMatch &other) const; |
70 | |
71 | /** |
72 | * @return the runner associated with this action |
73 | */ |
74 | AbstractRunner *runner() const; |
75 | |
76 | /** |
77 | * @return true if the match is valid and can therefore be run, |
78 | * an invalid match does not have an associated AbstractRunner |
79 | */ |
80 | bool isValid() const; |
81 | |
82 | /** |
83 | * Sets the type of match this action represents. |
84 | * This value is used for sorting the different categories |
85 | */ |
86 | void setType(Type type); |
87 | |
88 | /** |
89 | * The type of action this is. Defaults to PossibleMatch. |
90 | */ |
91 | Type type() const; |
92 | |
93 | /** |
94 | * Helper for reading standardized category relevance values |
95 | */ |
96 | enum class CategoryRelevance { |
97 | Lowest = 0, |
98 | Low = 30, |
99 | Moderate = 50, |
100 | High = 70, |
101 | Highest = 100, |
102 | }; |
103 | |
104 | /** |
105 | * Relevance for matches in the category. The match with the highest relevance is respected for the entire category. |
106 | * This value only affects the sorting of categories and not the sorting within the category. Use @ref setRelevance for this. |
107 | * The value should be from 0 to 100. |
108 | * |
109 | * @since 6.0 |
110 | */ |
111 | void setCategoryRelevance(CategoryRelevance relevance) |
112 | { |
113 | setCategoryRelevance(qToUnderlying(relevance)); |
114 | } |
115 | |
116 | /** |
117 | * @internal Internal for now, consumers should utilize CategoryRelevance enum |
118 | * |
119 | * @since 6.0 |
120 | */ |
121 | void setCategoryRelevance(qreal relevance); |
122 | |
123 | /** |
124 | * Category relevance for this match |
125 | * |
126 | * @since 6.0 |
127 | */ |
128 | qreal categoryRelevance() const; |
129 | |
130 | /** |
131 | * Sets information about the type of the match which is |
132 | * used to group the matches. |
133 | * |
134 | * This string should be translated as it is displayed in an UI. |
135 | * The default is @ref AbstractRunner::name |
136 | */ |
137 | void setMatchCategory(const QString &category); |
138 | |
139 | /** |
140 | * Extra information about the match which can be used |
141 | * to categorize the type. |
142 | * |
143 | * The default is @ref AbstractRunner::name |
144 | */ |
145 | QString matchCategory() const; |
146 | |
147 | /** |
148 | * Sets the relevance of this action for the search |
149 | * it was created for. |
150 | * |
151 | * @param relevance a number between 0 and 1. |
152 | */ |
153 | void setRelevance(qreal relevance); |
154 | |
155 | /** |
156 | * The relevance of this action to the search. By default, |
157 | * the relevance is 1. |
158 | * |
159 | * @return a number between 0 and 1 |
160 | */ |
161 | qreal relevance() const; |
162 | |
163 | /** |
164 | * Sets data to be used internally by the runner's @ref AbstractRunner::run implementation. |
165 | * |
166 | * When set, it is also used to form part of the @ref id for this match. |
167 | * If that is inappropriate as an id, the runner may generate its own |
168 | * id and set that with @ref setId |
169 | */ |
170 | void setData(const QVariant &data); |
171 | |
172 | /** |
173 | * @return the data associated with this match; usually runner-specific |
174 | */ |
175 | QVariant data() const; |
176 | |
177 | /** |
178 | * Sets the id for this match; useful if the id does not |
179 | * match data().toString(). The id must be unique to all |
180 | * matches from this runner, and should remain constant |
181 | * for the same query for best results. |
182 | * |
183 | * If the "X-Plasma-Runner-Unique-Results" property from the metadata |
184 | * is set to true, the runnerId will not be prepended to the ID. |
185 | * This allows KRunner to de-duplicate results from different runners. |
186 | * In case the runner's matches are less specific than ones from other runners, the |
187 | * "X-Plasma-Runner-Weak-Results" property can be set so that duplicates from this |
188 | * runner are removed. |
189 | * |
190 | * @param id the new identifying string to use to refer |
191 | * to this entry |
192 | */ |
193 | void setId(const QString &id); |
194 | |
195 | /** |
196 | * @return a string that can be used as an ID for this match, |
197 | * even between different queries. It is based in part |
198 | * on the source of the match (the AbstractRunner) and |
199 | * distinguishing information provided by the runner, |
200 | * ensuring global uniqueness as well as consistency |
201 | * between query matches. |
202 | */ |
203 | QString id() const; |
204 | |
205 | /** |
206 | * Sets the main title text for this match; should be short |
207 | * enough to fit nicely on one line in a user interface |
208 | * For styled and multiline text, @ref setMultiLine should be set to true |
209 | * |
210 | * @param text the text to use as the title |
211 | */ |
212 | void setText(const QString &text); |
213 | |
214 | /** |
215 | * @return the title text for this match |
216 | */ |
217 | QString text() const; |
218 | |
219 | /** |
220 | * Sets the descriptive text for this match; can be longer |
221 | * than the main title text |
222 | * |
223 | * @param text the text to use as the description |
224 | */ |
225 | void setSubtext(const QString &text); |
226 | |
227 | /** |
228 | * @return the descriptive text for this match |
229 | */ |
230 | QString subtext() const; |
231 | |
232 | /** |
233 | * Sets the icon associated with this match |
234 | * |
235 | * Prefer using setIconName. |
236 | * |
237 | * @param icon the icon to show along with the match |
238 | */ |
239 | void setIcon(const QIcon &icon); |
240 | |
241 | /** |
242 | * @return the icon for this match |
243 | */ |
244 | QIcon icon() const; |
245 | |
246 | /** |
247 | * Sets the icon name associated with this match |
248 | * |
249 | * @param icon the name of the icon to show along with the match |
250 | * @since 5.24 |
251 | */ |
252 | void setIconName(const QString &iconName); |
253 | |
254 | /** |
255 | * @return the name of the icon for this match |
256 | * @since 5.24 |
257 | */ |
258 | QString iconName() const; |
259 | |
260 | /** |
261 | * Sets the urls, if any, associated with this match |
262 | */ |
263 | void setUrls(const QList<QUrl> &urls); |
264 | |
265 | /** |
266 | * @return the urls for this match, empty list if none |
267 | * These will be used in the default implementation of AbstractRunner::mimeDataForMatch |
268 | */ |
269 | QList<QUrl> urls() const; |
270 | |
271 | /** |
272 | * Sets whether or not this match can be activited |
273 | * |
274 | * @param enable true if the match is enabled and therefore runnable |
275 | */ |
276 | void setEnabled(bool enable); |
277 | |
278 | /** |
279 | * @return true if the match is enabled and therefore runnable, otherwise false |
280 | */ |
281 | bool isEnabled() const; |
282 | |
283 | /** |
284 | * Set the actions for this match. |
285 | * This method allows you to set the actions inside of the AbstractRunner::match method |
286 | * @see RunnerManager::actionsForMatch |
287 | * @since 5.75 |
288 | */ |
289 | void setActions(const QList<KRunner::Action> &actions); |
290 | |
291 | /** |
292 | * Adds an action to this match |
293 | * @since 5.75 |
294 | * @see setActions |
295 | */ |
296 | void addAction(const KRunner::Action &action); |
297 | |
298 | /** |
299 | * List of actions set for this match |
300 | * @return actions |
301 | * @since 5.75 |
302 | */ |
303 | QList<KRunner::Action> actions() const; |
304 | |
305 | /** |
306 | * The action that the user has selected when running the match. |
307 | * This returns a nullptr if no action was selected. |
308 | */ |
309 | KRunner::Action selectedAction() const; |
310 | |
311 | /** |
312 | * Set if the text should be displayed as a multiLine string |
313 | * @param multiLine |
314 | * @since 5.82 |
315 | */ |
316 | void setMultiLine(bool multiLine); |
317 | |
318 | /** |
319 | * If the text should be displayed as a multiLine string |
320 | * If no explicit value is set set using setMultiline it will default to false |
321 | * @return bool |
322 | * @since 5.82 |
323 | */ |
324 | bool isMultiLine() const; |
325 | |
326 | private: |
327 | KRUNNER_NO_EXPORT void setSelectedAction(const KRunner::Action &action); |
328 | friend class RunnerManager; |
329 | QSharedDataPointer<QueryMatchPrivate> d; |
330 | }; |
331 | |
332 | /// @since 6.0 |
333 | KRUNNER_EXPORT QDebug operator<<(QDebug debug, const KRunner::QueryMatch &match); |
334 | } |
335 | #endif |
336 | |