/* SPDX-FileCopyrightText: 2006-2007 Aaron Seigo SPDX-FileCopyrightText: 2023 Alexander Lohnau SPDX-License-Identifier: LGPL-2.0-or-later */ #ifndef KRUNNER_QUERYMATCH_H #define KRUNNER_QUERYMATCH_H #include #include #include #include "krunner_export.h" class QIcon; class QVariant; namespace KRunner { class Action; class AbstractRunner; class QueryMatchPrivate; /*! * \class KRunner::QueryMatch * \inheaderfile KRunner/QueryMatch * \inmodule KRunner * * \brief A match returned by an AbstractRunner in response to a given RunnerContext. */ class KRUNNER_EXPORT QueryMatch { public: /*! * Constructs a PossibleMatch associated with a given RunnerContext * and runner. * * \a runner the runner this match belongs to */ explicit QueryMatch(AbstractRunner *runner = nullptr); QueryMatch(const QueryMatch &other); ~QueryMatch(); QueryMatch &operator=(const QueryMatch &other); bool operator==(const QueryMatch &other) const; bool operator!=(const QueryMatch &other) const; /*! * Returns the runner associated with this action */ AbstractRunner *runner() const; /*! * Returns true if the match is valid and can therefore be run, * an invalid match does not have an associated AbstractRunner */ bool isValid() const; /*! * Helper for reading standardized category relevance values * * \value Lowest * \value Low * \value Moderate * \value High * \value Highest */ enum class CategoryRelevance { Lowest = 0, Low = 30, Moderate = 50, High = 70, Highest = 100, }; /*! * Relevance for matches in the category. The match with the highest relevance is respected for the entire category. * This value only affects the sorting of categories and not the sorting within the category. Use setRelevance for this. * The value should be from 0 to 100. * * \since 6.0 */ void setCategoryRelevance(CategoryRelevance relevance) { setCategoryRelevance(qToUnderlying(relevance)); } /*! * \internal Internal for now, consumers should utilize CategoryRelevance enum * * \since 6.0 */ void setCategoryRelevance(qreal relevance); /*! * Category relevance for this match * * \since 6.0 */ qreal categoryRelevance() const; /*! * Sets information about the type of the match which is * used to group the matches. * * This string should be translated as it is displayed in an UI. * The default is AbstractRunner::name */ void setMatchCategory(const QString &category); /*! * Extra information about the match which can be used * to categorize the type. * * The default is AbstractRunner::name */ QString matchCategory() const; /*! * Sets the relevance of this action for the search * it was created for. * * \a relevance a number between 0 and 1. */ void setRelevance(qreal relevance); /*! * The relevance of this action to the search. By default, * the relevance is 1. * * Returns a number between 0 and 1 */ qreal relevance() const; /*! * Sets data to be used internally by the runner's AbstractRunner::run implementation. * * When set, it is also used to form part of the id for this match. * If that is inappropriate as an id, the runner may generate its own * id and set that with setId */ void setData(const QVariant &data); /*! * Returns the data associated with this match; usually runner-specific */ QVariant data() const; /*! * Sets the id for this match; useful if the id does not * match data().toString(). The id must be unique to all * matches from this runner, and should remain constant * for the same query for best results. * * If the "X-Plasma-Runner-Unique-Results" property from the metadata * is set to true, the runnerId will not be prepended to the ID. * This allows KRunner to de-duplicate results from different runners. * In case the runner's matches are less specific than ones from other runners, the * "X-Plasma-Runner-Weak-Results" property can be set so that duplicates from this * runner are removed. * * \a id the new identifying string to use to refer * to this entry */ void setId(const QString &id); /*! * Returns a string that can be used as an ID for this match, * even between different queries. It is based in part * on the source of the match (the AbstractRunner) and * distinguishing information provided by the runner, * ensuring global uniqueness as well as consistency * between query matches. */ QString id() const; /*! * Sets the main title text for this match; should be short * enough to fit nicely on one line in a user interface * For styled and multiline text, setMultiLine should be set to true * * \a text the text to use as the title */ void setText(const QString &text); /*! * Returns the title text for this match */ QString text() const; /*! * Sets the descriptive text for this match; can be longer * than the main title text * * \a text the text to use as the description */ void setSubtext(const QString &text); /*! * Returns the descriptive text for this match */ QString subtext() const; /*! * Sets the icon associated with this match * * Prefer using setIconName. * * \a icon the icon to show along with the match */ void setIcon(const QIcon &icon); /*! * Returns the icon for this match */ QIcon icon() const; /*! * Sets the icon name associated with this match * * \a icon the name of the icon to show along with the match * \since 5.24 */ void setIconName(const QString &iconName); /*! * Returns the name of the icon for this match * \since 5.24 */ QString iconName() const; /*! * Sets the urls, if any, associated with this match */ void setUrls(const QList &urls); /*! * Returns the urls for this match, empty list if none * These will be used in the default implementation of AbstractRunner::mimeDataForMatch */ QList urls() const; /*! * Sets whether or not this match can be activited * * \a enable true if the match is enabled and therefore runnable */ void setEnabled(bool enable); /*! * Returns true if the match is enabled and therefore runnable, otherwise false */ bool isEnabled() const; /*! * Set the actions for this match. * This method allows you to set the actions inside of the AbstractRunner::match method * \sa RunnerManager::actionsForMatch * \since 5.75 */ void setActions(const QList &actions); /*! * Adds an action to this match * \since 5.75 * \sa setActions */ void addAction(const KRunner::Action &action); /*! * List of actions set for this match * Returns actions * \since 5.75 */ QList actions() const; /*! * The action that the user has selected when running the match. * This returns a nullptr if no action was selected. */ KRunner::Action selectedAction() const; /*! * Set if the text should be displayed as a multiLine string * * \a multiLine * \since 5.82 */ void setMultiLine(bool multiLine); /*! * If the text should be displayed as a multiLine string * If no explicit value is set set using setMultiline it will default to false * Returns bool * \since 5.82 */ bool isMultiLine() const; private: KRUNNER_NO_EXPORT void setSelectedAction(const KRunner::Action &action); friend class RunnerManager; QSharedDataPointer d; }; /// \since 6.0 KRUNNER_EXPORT QDebug operator<<(QDebug debug, const KRunner::QueryMatch &match); } #endif