1 /* 2 SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <aseigo@kde.org> 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 InformationalMatch = 50, /**< A purely informational, non-runnable match, 45 such as the answer to a question or calculation. 46 The data of the match will be converted to a string 47 and set in the search field */ 48 HelperMatch = 70, /**< A match that represents an action not directly related 49 to activating the given search term, such as a search 50 in an external tool or a command learning trigger. Helper 51 matches tend to be generic to the query and should not 52 be autoactivated just because the user hits "Enter" 53 while typing. They must be explicitly selected to 54 be activated, but unlike InformationalMatch cause 55 an action to be triggered. */ 56 ExactMatch = 100, /**< An exact match to the query */ 57 }; 58 59 /** 60 * Constructs a PossibleMatch associated with a given RunnerContext 61 * and runner. 62 * 63 * @param runner the runner this match belongs to 64 */ 65 explicit QueryMatch(AbstractRunner *runner = nullptr); 66 67 /** 68 * Copy constructor 69 */ 70 QueryMatch(const QueryMatch &other); 71 72 ~QueryMatch(); 73 QueryMatch &operator=(const QueryMatch &other); 74 bool operator==(const QueryMatch &other) const; 75 bool operator!=(const QueryMatch &other) const; 76 bool operator<(const QueryMatch &other) const; 77 78 /** 79 * @return the runner associated with this action 80 */ 81 AbstractRunner *runner() const; 82 83 /** 84 * Requests this match to activae using the given context 85 * 86 * @param context the context to use in conjunction with this run 87 * 88 * @sa AbstractRunner::run 89 */ 90 void run(const RunnerContext &context) const; 91 92 /** 93 * @return true if the match is valid and can therefore be run, 94 * an invalid match does not have an associated AbstractRunner 95 */ 96 bool isValid() const; 97 98 /** 99 * Sets the type of match this action represents. 100 */ 101 void setType(Type type); 102 103 /** 104 * The type of action this is. Defaults to PossibleMatch. 105 */ 106 Type type() const; 107 108 /** 109 * Sets information about the type of the match which can 110 * be used to categorize the match. 111 * 112 * This string should be translated as it can be displayed 113 * in an UI 114 */ 115 void setMatchCategory(const QString &category); 116 117 /** 118 * Extra information about the match which can be used 119 * to categorize the type. 120 * 121 * By default this returns the internal name of the runner 122 * which returned this result 123 */ 124 QString matchCategory() const; 125 126 /** 127 * Sets the relevance of this action for the search 128 * it was created for. 129 * 130 * @param relevance a number between 0 and 1. 131 */ 132 void setRelevance(qreal relevance); 133 134 /** 135 * The relevance of this action to the search. By default, 136 * the relevance is 1. 137 * 138 * @return a number between 0 and 1 139 */ 140 qreal relevance() const; 141 142 /** 143 * Sets data to be used internally by the associated 144 * AbstractRunner. 145 * 146 * When set, it is also used to form 147 * part of the id() for this match. If that is inappropriate 148 * as an id, the runner may generate its own id and set that 149 * with setId(const QString&) directly after calling setData 150 */ 151 void setData(const QVariant &data); 152 153 /** 154 * @return the data associated with this match; usually runner-specific 155 */ 156 QVariant data() const; 157 158 /** 159 * Sets the id for this match; useful if the id does not 160 * match data().toString(). The id must be unique to all 161 * matches from this runner, and should remain constant 162 * for the same query for best results. 163 * 164 * @param id the new identifying string to use to refer 165 * to this entry 166 */ 167 void setId(const QString &id); 168 169 /** 170 * @return a string that can be used as an ID for this match, 171 * even between different queries. It is based in part 172 * on the source of the match (the AbstractRunner) and 173 * distinguishing information provided by the runner, 174 * ensuring global uniqueness as well as consistency 175 * between query matches. 176 */ 177 QString id() const; 178 179 /** 180 * Sets the main title text for this match; should be short 181 * enough to fit nicely on one line in a user interface 182 * 183 * @param text the text to use as the title 184 */ 185 void setText(const QString &text); 186 187 /** 188 * @return the title text for this match 189 */ 190 QString text() const; 191 192 /** 193 * Sets the descriptive text for this match; can be longer 194 * than the main title text 195 * 196 * @param text the text to use as the description 197 */ 198 void setSubtext(const QString &text); 199 200 /** 201 * @return the descriptive text for this match 202 */ 203 QString subtext() const; 204 205 /** 206 * Sets the icon associated with this match 207 * 208 * Prefer using setIconName. 209 * 210 * @param icon the icon to show along with the match 211 */ 212 void setIcon(const QIcon &icon); 213 214 /** 215 * @return the icon for this match 216 */ 217 QIcon icon() const; 218 219 /** 220 * Sets the icon name associated with this match 221 * 222 * @param icon the name of the icon to show along with the match 223 * @since 5.24 224 */ 225 void setIconName(const QString &iconName); 226 227 /** 228 * @return the name of the icon for this match 229 * @since 5.24 230 */ 231 QString iconName() const; 232 233 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 82) 234 /** 235 * Sets the MimeType, if any, associated with this match. 236 * This overrides the MimeType provided by QueryContext, and should only be 237 * set when it is different from the QueryContext MimeType 238 * @deprecated Since 5.82, deprecated for lack of usage 239 */ 240 KRUNNER_DEPRECATED_VERSION(5, 82, "deprecated for lack of usage") 241 void setMimeType(const QString &mimeType); 242 243 /** 244 * @return the mimtype for this match, or QString() is none 245 * @deprecated Since 5.82, deprecated for lack of usage 246 */ 247 KRUNNER_DEPRECATED_VERSION(5, 82, "deprecated for lack of usage") 248 QString mimeType() const; 249 #endif 250 251 /** 252 * Sets the urls, if any, associated with this match 253 */ 254 void setUrls(const QList<QUrl> &urls); 255 256 /** 257 * @return the mimtype for this match, or QString() is none 258 */ 259 QList<QUrl> urls() const; 260 261 /** 262 * Sets whether or not this match can be activited 263 * 264 * @param enable true if the match is enabled and therefore runnable 265 */ 266 void setEnabled(bool enable); 267 268 /** 269 * @return true if the match is enabled and therefore runnable, otherwise false 270 */ 271 bool isEnabled() const; 272 273 /** 274 * Set the actions for this match. 275 * This method allows you to set the actions inside of the AbstractRunner::match() method 276 * and the default implementation of AbstractRunner::actionsForMatch() will return these. 277 * @since 5.75 278 */ 279 void setActions(const QList<QAction *> &actions); 280 281 /** 282 * Adds an action to this match 283 * @since 5.75 284 * @see setActions 285 */ 286 void addAction(QAction *actions); 287 288 /** 289 * List of actions set for this match 290 * @return actions 291 * @since 5.75 292 */ 293 QList<QAction *> actions() const; 294 295 /** 296 * The current action. 297 */ 298 QAction *selectedAction() const; 299 300 /** 301 * Sets the selected action 302 */ 303 void setSelectedAction(QAction *action); 304 305 /** 306 * Set if the text should be displayed as a multiLine string 307 * @param multiLine 308 * @since 5.82 309 */ 310 void setMultiLine(bool multiLine); 311 312 /** 313 * If the text should be displayed as a multiLine string 314 * If no explicit value is set set using setMultiline it will default to false 315 * @return bool 316 * @since 5.82 317 */ 318 bool isMultiLine() const; 319 320 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71) 321 /** 322 * @return true if this match can be configured before being run 323 * @since 4.3 324 * @deprecated Since 5.0, this feature has been defunct 325 */ 326 KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed") 327 bool hasConfigurationInterface() const; 328 #endif 329 330 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71) 331 /** 332 * If hasConfigurationInterface() returns true, this method may be called to get 333 * a widget displaying the options the user can interact with to modify 334 * the behaviour of what happens when the match is run. 335 * 336 * @param widget the parent of the options widgets. 337 * @since 4.3 338 * @deprecated Since 5.0, this feature has been defunct 339 */ 340 KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed") 341 void createConfigurationInterface(QWidget *parent); 342 #endif 343 344 private: 345 QSharedDataPointer<QueryMatchPrivate> d; 346 }; 347 348 } 349 350 #endif 351