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

source code of krunner/src/querymatch.h