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

source code of krunner/src/querymatch.h