File indexing completed on 2024-03-24 03:59:37
0001 /* 0002 SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <aseigo@kde.org> 0003 SPDX-FileCopyrightText: 2023 Alexander Lohnau <alexander.lohnau@gmx.de> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KRUNNER_QUERYMATCH_H 0009 #define KRUNNER_QUERYMATCH_H 0010 0011 #include <QList> 0012 #include <QSharedDataPointer> 0013 #include <QUrl> 0014 0015 #include "krunner_export.h" 0016 0017 class QIcon; 0018 class QVariant; 0019 0020 namespace KRunner 0021 { 0022 class Action; 0023 class AbstractRunner; 0024 class QueryMatchPrivate; 0025 0026 /** 0027 * @class QueryMatch querymatch.h <KRunner/QueryMatch> 0028 * 0029 * @short A match returned by an AbstractRunner in response to a given RunnerContext. 0030 */ 0031 class KRUNNER_EXPORT QueryMatch 0032 { 0033 public: 0034 /** 0035 * Constructs a PossibleMatch associated with a given RunnerContext 0036 * and runner. 0037 * 0038 * @param runner the runner this match belongs to 0039 */ 0040 explicit QueryMatch(AbstractRunner *runner = nullptr); 0041 0042 /** 0043 * Copy constructor 0044 */ 0045 QueryMatch(const QueryMatch &other); 0046 0047 ~QueryMatch(); 0048 QueryMatch &operator=(const QueryMatch &other); 0049 bool operator==(const QueryMatch &other) const; 0050 bool operator!=(const QueryMatch &other) const; 0051 0052 /** 0053 * @return the runner associated with this action 0054 */ 0055 AbstractRunner *runner() const; 0056 0057 /** 0058 * @return true if the match is valid and can therefore be run, 0059 * an invalid match does not have an associated AbstractRunner 0060 */ 0061 bool isValid() const; 0062 0063 /** 0064 * Helper for reading standardized category relevance values 0065 */ 0066 enum class CategoryRelevance { 0067 Lowest = 0, 0068 Low = 30, 0069 Moderate = 50, 0070 High = 70, 0071 Highest = 100, 0072 }; 0073 0074 /** 0075 * Relevance for matches in the category. The match with the highest relevance is respected for the entire category. 0076 * This value only affects the sorting of categories and not the sorting within the category. Use @ref setRelevance for this. 0077 * The value should be from 0 to 100. 0078 * 0079 * @since 6.0 0080 */ 0081 void setCategoryRelevance(CategoryRelevance relevance) 0082 { 0083 setCategoryRelevance(qToUnderlying(relevance)); 0084 } 0085 0086 /** 0087 * @internal Internal for now, consumers should utilize CategoryRelevance enum 0088 * 0089 * @since 6.0 0090 */ 0091 void setCategoryRelevance(qreal relevance); 0092 0093 /** 0094 * Category relevance for this match 0095 * 0096 * @since 6.0 0097 */ 0098 qreal categoryRelevance() const; 0099 0100 /** 0101 * Sets information about the type of the match which is 0102 * used to group the matches. 0103 * 0104 * This string should be translated as it is displayed in an UI. 0105 * The default is @ref AbstractRunner::name 0106 */ 0107 void setMatchCategory(const QString &category); 0108 0109 /** 0110 * Extra information about the match which can be used 0111 * to categorize the type. 0112 * 0113 * The default is @ref AbstractRunner::name 0114 */ 0115 QString matchCategory() const; 0116 0117 /** 0118 * Sets the relevance of this action for the search 0119 * it was created for. 0120 * 0121 * @param relevance a number between 0 and 1. 0122 */ 0123 void setRelevance(qreal relevance); 0124 0125 /** 0126 * The relevance of this action to the search. By default, 0127 * the relevance is 1. 0128 * 0129 * @return a number between 0 and 1 0130 */ 0131 qreal relevance() const; 0132 0133 /** 0134 * Sets data to be used internally by the runner's @ref AbstractRunner::run implementation. 0135 * 0136 * When set, it is also used to form part of the @ref id for this match. 0137 * If that is inappropriate as an id, the runner may generate its own 0138 * id and set that with @ref setId 0139 */ 0140 void setData(const QVariant &data); 0141 0142 /** 0143 * @return the data associated with this match; usually runner-specific 0144 */ 0145 QVariant data() const; 0146 0147 /** 0148 * Sets the id for this match; useful if the id does not 0149 * match data().toString(). The id must be unique to all 0150 * matches from this runner, and should remain constant 0151 * for the same query for best results. 0152 * 0153 * If the "X-Plasma-Runner-Unique-Results" property from the metadata 0154 * is set to true, the runnerId will not be prepended to the ID. 0155 * This allows KRunner to de-duplicate results from different runners. 0156 * In case the runner's matches are less specific than ones from other runners, the 0157 * "X-Plasma-Runner-Weak-Results" property can be set so that duplicates from this 0158 * runner are removed. 0159 * 0160 * @param id the new identifying string to use to refer 0161 * to this entry 0162 */ 0163 void setId(const QString &id); 0164 0165 /** 0166 * @return a string that can be used as an ID for this match, 0167 * even between different queries. It is based in part 0168 * on the source of the match (the AbstractRunner) and 0169 * distinguishing information provided by the runner, 0170 * ensuring global uniqueness as well as consistency 0171 * between query matches. 0172 */ 0173 QString id() const; 0174 0175 /** 0176 * Sets the main title text for this match; should be short 0177 * enough to fit nicely on one line in a user interface 0178 * For styled and multiline text, @ref setMultiLine should be set to true 0179 * 0180 * @param text the text to use as the title 0181 */ 0182 void setText(const QString &text); 0183 0184 /** 0185 * @return the title text for this match 0186 */ 0187 QString text() const; 0188 0189 /** 0190 * Sets the descriptive text for this match; can be longer 0191 * than the main title text 0192 * 0193 * @param text the text to use as the description 0194 */ 0195 void setSubtext(const QString &text); 0196 0197 /** 0198 * @return the descriptive text for this match 0199 */ 0200 QString subtext() const; 0201 0202 /** 0203 * Sets the icon associated with this match 0204 * 0205 * Prefer using setIconName. 0206 * 0207 * @param icon the icon to show along with the match 0208 */ 0209 void setIcon(const QIcon &icon); 0210 0211 /** 0212 * @return the icon for this match 0213 */ 0214 QIcon icon() const; 0215 0216 /** 0217 * Sets the icon name associated with this match 0218 * 0219 * @param icon the name of the icon to show along with the match 0220 * @since 5.24 0221 */ 0222 void setIconName(const QString &iconName); 0223 0224 /** 0225 * @return the name of the icon for this match 0226 * @since 5.24 0227 */ 0228 QString iconName() const; 0229 0230 /** 0231 * Sets the urls, if any, associated with this match 0232 */ 0233 void setUrls(const QList<QUrl> &urls); 0234 0235 /** 0236 * @return the urls for this match, empty list if none 0237 * These will be used in the default implementation of AbstractRunner::mimeDataForMatch 0238 */ 0239 QList<QUrl> urls() const; 0240 0241 /** 0242 * Sets whether or not this match can be activited 0243 * 0244 * @param enable true if the match is enabled and therefore runnable 0245 */ 0246 void setEnabled(bool enable); 0247 0248 /** 0249 * @return true if the match is enabled and therefore runnable, otherwise false 0250 */ 0251 bool isEnabled() const; 0252 0253 /** 0254 * Set the actions for this match. 0255 * This method allows you to set the actions inside of the AbstractRunner::match method 0256 * @see RunnerManager::actionsForMatch 0257 * @since 5.75 0258 */ 0259 void setActions(const QList<KRunner::Action> &actions); 0260 0261 /** 0262 * Adds an action to this match 0263 * @since 5.75 0264 * @see setActions 0265 */ 0266 void addAction(const KRunner::Action &action); 0267 0268 /** 0269 * List of actions set for this match 0270 * @return actions 0271 * @since 5.75 0272 */ 0273 QList<KRunner::Action> actions() const; 0274 0275 /** 0276 * The action that the user has selected when running the match. 0277 * This returns a nullptr if no action was selected. 0278 */ 0279 KRunner::Action selectedAction() const; 0280 0281 /** 0282 * Set if the text should be displayed as a multiLine string 0283 * @param multiLine 0284 * @since 5.82 0285 */ 0286 void setMultiLine(bool multiLine); 0287 0288 /** 0289 * If the text should be displayed as a multiLine string 0290 * If no explicit value is set set using setMultiline it will default to false 0291 * @return bool 0292 * @since 5.82 0293 */ 0294 bool isMultiLine() const; 0295 0296 private: 0297 KRUNNER_NO_EXPORT void setSelectedAction(const KRunner::Action &action); 0298 friend class RunnerManager; 0299 QSharedDataPointer<QueryMatchPrivate> d; 0300 }; 0301 0302 /// @since 6.0 0303 KRUNNER_EXPORT QDebug operator<<(QDebug debug, const KRunner::QueryMatch &match); 0304 } 0305 #endif