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
17class QIcon;
18class QVariant;
19
20namespace KRunner
21{
22class Action;
23class AbstractRunner;
24class 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 */
31class KRUNNER_EXPORT QueryMatch
32{
33public:
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
326private:
327 KRUNNER_NO_EXPORT void setSelectedAction(const KRunner::Action &action);
328 friend class RunnerManager;
329 QSharedDataPointer<QueryMatchPrivate> d;
330};
331
332/// @since 6.0
333KRUNNER_EXPORT QDebug operator<<(QDebug debug, const KRunner::QueryMatch &match);
334}
335#endif
336

source code of krunner/src/querymatch.h