KRunner

querymatch.h
1 /*
2  SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef PLASMA_QUERYMATCH_H
8 #define PLASMA_QUERYMATCH_H
9 
10 #include <QList>
11 #include <QSharedDataPointer>
12 #include <QUrl>
13 
14 #include "krunner_export.h"
15 
16 class QAction;
17 class QIcon;
18 class QString;
19 class QVariant;
20 class QWidget;
21 
22 namespace Plasma
23 {
24 class RunnerContext;
25 class AbstractRunner;
26 class QueryMatchPrivate;
27 
28 /**
29  * @class QueryMatch querymatch.h <KRunner/QueryMatch>
30  *
31  * @short A match returned by an AbstractRunner in response to a given
32  * RunnerContext.
33  */
34 class KRUNNER_EXPORT QueryMatch
35 {
36 public:
37  /**
38  * The type of match. Value is important here as it is used for sorting
39  */
40  enum Type {
41  NoMatch = 0, /**< Null match */
42  CompletionMatch = 10, /**< Possible completion for the data of the query */
43  PossibleMatch = 30, /**< Something that may match the query */
44 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 99)
45  /**
46  * A purely informational, non-runnable match, such as the answer to a question or calculation.
47  * The data of the match will be converted to a string and set in the search field.
48  * @deprecated Since 5.99, call RunnerContext::requestQueryStringUpdate in AbstractRunner::run method instead
49  */
50  InformationalMatch KRUNNER_ENUMERATOR_DEPRECATED_VERSION(5, 99, "Call RunnerContext::requestQueryStringUpdate in AbstractRunner::run method instead") =
51  50,
52 #endif
53  /**
54  * A match that represents an action not directly related
55  * to activating the given search term, such as a search
56  * in an external tool or a command learning trigger. Helper
57  * matches tend to be generic to the query and should not
58  * be autoactivated just because the user hits "Enter"
59  * while typing. They must be explicitly selected to
60  * be activated, but unlike InformationalMatch cause
61  * an action to be triggered.
62  */
63  HelperMatch = 70,
64  ExactMatch = 100, /**< An exact match to the query */
65  };
66 
67  /**
68  * Constructs a PossibleMatch associated with a given RunnerContext
69  * and runner.
70  *
71  * @param runner the runner this match belongs to
72  */
73  explicit QueryMatch(AbstractRunner *runner = nullptr);
74 
75  /**
76  * Copy constructor
77  */
78  QueryMatch(const QueryMatch &other);
79 
80  ~QueryMatch();
81  QueryMatch &operator=(const QueryMatch &other);
82  bool operator==(const QueryMatch &other) const;
83  bool operator!=(const QueryMatch &other) const;
84  bool operator<(const QueryMatch &other) const;
85 
86  /**
87  * @return the runner associated with this action
88  */
89  AbstractRunner *runner() const;
90 
91  /**
92  * Requests this match to activae using the given context
93  *
94  * @param context the context to use in conjunction with this run
95  *
96  * @sa AbstractRunner::run
97  */
98  void run(const RunnerContext &context) const;
99 
100  /**
101  * @return true if the match is valid and can therefore be run,
102  * an invalid match does not have an associated AbstractRunner
103  */
104  bool isValid() const;
105 
106 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 113)
107  /**
108  * Sets the type of match this action represents.
109  */
110  KRUNNER_DEPRECATED_VERSION(5, 113, "Use setCategoryRelevance instead")
111  void setType(Type type);
112 #endif
113 
114  /**
115  * The type of action this is. Defaults to PossibleMatch.
116  */
117  Type type() const;
118 
119  /**
120  * Helper for reading standardized category relevance values
121  */
122  enum class CategoryRelevance {
123  Lowest = 0,
124  Low = 30,
125  Moderate = 51,
126  High = 70,
127  Highest = 100,
128  };
129 
130  /**
131  * Relevance for matches in the category. The match with the highest relevance is respected for the entire category.
132  * This value only affects the sorting of categories and not the sorting within the category. Use @ref setRelevance for this.
133  * The value should be from 0 to 100.
134  *
135  * @since 5.113
136  */
137  void setCategoryRelevance(CategoryRelevance relevance);
138 
139  /**
140  * Sets information about the type of the match which can
141  * be used to categorize the match.
142  *
143  * This string should be translated as it can be displayed
144  * in an UI
145  */
146  void setMatchCategory(const QString &category);
147 
148  /**
149  * Extra information about the match which can be used
150  * to categorize the type.
151  *
152  * By default this returns the internal name of the runner
153  * which returned this result
154  */
155  QString matchCategory() const;
156 
157  /**
158  * Sets the relevance of this action for the search
159  * it was created for.
160  *
161  * @param relevance a number between 0 and 1.
162  */
163  void setRelevance(qreal relevance);
164 
165  /**
166  * The relevance of this action to the search. By default,
167  * the relevance is 1.
168  *
169  * @return a number between 0 and 1
170  */
171  qreal relevance() const;
172 
173  /**
174  * Sets data to be used internally by the associated
175  * AbstractRunner.
176  *
177  * When set, it is also used to form
178  * part of the id() for this match. If that is inappropriate
179  * as an id, the runner may generate its own id and set that
180  * with setId(const QString&) directly after calling setData
181  */
182  void setData(const QVariant &data);
183 
184  /**
185  * @return the data associated with this match; usually runner-specific
186  */
187  QVariant data() const;
188 
189  /**
190  * Sets the id for this match; useful if the id does not
191  * match data().toString(). The id must be unique to all
192  * matches from this runner, and should remain constant
193  * for the same query for best results.
194  *
195  * @param id the new identifying string to use to refer
196  * to this entry
197  */
198  void setId(const QString &id);
199 
200  /**
201  * @return a string that can be used as an ID for this match,
202  * even between different queries. It is based in part
203  * on the source of the match (the AbstractRunner) and
204  * distinguishing information provided by the runner,
205  * ensuring global uniqueness as well as consistency
206  * between query matches.
207  */
208  QString id() const;
209 
210  /**
211  * Sets the main title text for this match; should be short
212  * enough to fit nicely on one line in a user interface
213  *
214  * @param text the text to use as the title
215  */
216  void setText(const QString &text);
217 
218  /**
219  * @return the title text for this match
220  */
221  QString text() const;
222 
223  /**
224  * Sets the descriptive text for this match; can be longer
225  * than the main title text
226  *
227  * @param text the text to use as the description
228  */
229  void setSubtext(const QString &text);
230 
231  /**
232  * @return the descriptive text for this match
233  */
234  QString subtext() const;
235 
236  /**
237  * Sets the icon associated with this match
238  *
239  * Prefer using setIconName.
240  *
241  * @param icon the icon to show along with the match
242  */
243  void setIcon(const QIcon &icon);
244 
245  /**
246  * @return the icon for this match
247  */
248  QIcon icon() const;
249 
250  /**
251  * Sets the icon name associated with this match
252  *
253  * @param icon the name of the icon to show along with the match
254  * @since 5.24
255  */
256  void setIconName(const QString &iconName);
257 
258  /**
259  * @return the name of the icon for this match
260  * @since 5.24
261  */
262  QString iconName() const;
263 
264 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 82)
265  /**
266  * Sets the MimeType, if any, associated with this match.
267  * This overrides the MimeType provided by QueryContext, and should only be
268  * set when it is different from the QueryContext MimeType
269  * @deprecated Since 5.82, deprecated for lack of usage
270  */
271  KRUNNER_DEPRECATED_VERSION(5, 82, "deprecated for lack of usage")
272  void setMimeType(const QString &mimeType);
273 
274  /**
275  * @return the mimtype for this match, or QString() is none
276  * @deprecated Since 5.82, deprecated for lack of usage
277  */
278  KRUNNER_DEPRECATED_VERSION(5, 82, "deprecated for lack of usage")
279  QString mimeType() const;
280 #endif
281 
282  /**
283  * Sets the urls, if any, associated with this match
284  */
285  void setUrls(const QList<QUrl> &urls);
286 
287  /**
288  * @return the mimtype for this match, or QString() is none
289  */
290  QList<QUrl> urls() const;
291 
292  /**
293  * Sets whether or not this match can be activited
294  *
295  * @param enable true if the match is enabled and therefore runnable
296  */
297  void setEnabled(bool enable);
298 
299  /**
300  * @return true if the match is enabled and therefore runnable, otherwise false
301  */
302  bool isEnabled() const;
303 
304  /**
305  * Set the actions for this match.
306  * This method allows you to set the actions inside of the AbstractRunner::match() method
307  * and the default implementation of AbstractRunner::actionsForMatch() will return these.
308  * @since 5.75
309  */
310  void setActions(const QList<QAction *> &actions);
311 
312  /**
313  * Adds an action to this match
314  * @since 5.75
315  * @see setActions
316  */
317  void addAction(QAction *actions);
318 
319  /**
320  * List of actions set for this match
321  * @return actions
322  * @since 5.75
323  */
324  QList<QAction *> actions() const;
325 
326  /**
327  * The current action.
328  */
329  QAction *selectedAction() const;
330 
331  /**
332  * Sets the selected action
333  */
334  void setSelectedAction(QAction *action);
335 
336  /**
337  * Set if the text should be displayed as a multiLine string
338  * @param multiLine
339  * @since 5.82
340  */
341  void setMultiLine(bool multiLine);
342 
343  /**
344  * If the text should be displayed as a multiLine string
345  * If no explicit value is set set using setMultiline it will default to false
346  * @return bool
347  * @since 5.82
348  */
349  bool isMultiLine() const;
350 
351 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71)
352  /**
353  * @return true if this match can be configured before being run
354  * @since 4.3
355  * @deprecated Since 5.0, this feature has been defunct
356  */
357  KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed")
358  bool hasConfigurationInterface() const;
359 #endif
360 
361 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71)
362  /**
363  * If hasConfigurationInterface() returns true, this method may be called to get
364  * a widget displaying the options the user can interact with to modify
365  * the behaviour of what happens when the match is run.
366  *
367  * @param widget the parent of the options widgets.
368  * @since 4.3
369  * @deprecated Since 5.0, this feature has been defunct
370  */
371  KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed")
372  void createConfigurationInterface(QWidget *parent);
373 #endif
374 
375 private:
377 };
378 
379 }
380 
381 #if !KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
382 namespace KRunner
383 {
384 using QueryMatch = Plasma::QueryMatch;
385 using AbstractRunner = Plasma::AbstractRunner;
386 }
387 #endif
388 
389 #endif
A match returned by an AbstractRunner in response to a given RunnerContext.
Definition: querymatch.h:34
An abstract base class for Plasma Runner plugins.
Type
The type of match.
Definition: querymatch.h:40
The RunnerContext class provides information related to a search, including the search term,...
Definition: runnercontext.h:31
CategoryRelevance
Helper for reading standardized category relevance values.
Definition: querymatch.h:122
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 2 2023 03:51:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.