plasma/querymatch.h

   1 /*
   2  *   Copyright 2006-2007 Aaron Seigo <aseigo@kde.org>
   3  *
   4  *   This program is free software; you can redistribute it and/or modify
   5  *   it under the terms of the GNU Library General Public License as
   6  *   published by the Free Software Foundation; either version 2, or
   7  *   (at your option) any later version.
   8  *
   9  *   This program is distributed in the hope that it will be useful,
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  *   GNU General Public License for more details
  13  *
  14  *   You should have received a copy of the GNU Library General Public
  15  *   License along with this program; if not, write to the
  16  *   Free Software Foundation, Inc.,
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  18  */
  19
  20 #ifndef PLASMA_QUERYMATCH_H
  21 #define PLASMA_QUERYMATCH_H
  22
  23 #include <QtCore/QList>
  24 #include <QtCore/QSharedDataPointer>
  25
  26 #include <plasma/plasma_export.h>
  27
  28 class QAction;
  29 class QIcon;
  30 class QVariant;
  31 class QString;
  32
  33 namespace Plasma
  34 {
  35
  36 class RunnerContext;
  37 class AbstractRunner;
  38 class QueryMatchPrivate;
  39
  40 /**
  41  * @class QueryMatch plasma/querymatch.h <Plasma/QueryMatch>
  42  *
  43  * @short A match returned by an AbstractRunner in response to a given
  44  * RunnerContext.
  45  */
  46 class PLASMA_EXPORT QueryMatch
  47 {
  48     public:
  49         /**
  50          * The type of match. Value is important here as it is used for sorting
  51          */
  52         enum Type {
  53             NoMatch = 0,         /**< Null match */
  54             CompletionMatch = 10, /**< Possible completion for the data of the query */
  55             PossibleMatch = 30,   /**< Something that may match the query */
  56             InformationalMatch = 50, /**< A purely informational, non-actionable match,
  57                                        such as the answer to a question or calculation*/
  58             HelperMatch = 70, /**< A match that represents an action not directly related
  59                                  to activating the given search term, such as a search
  60                                  in an external tool or a command learning trigger. Helper
  61                                  matches tend to be generic to the query and should not
  62                                  be autoactivated just because the user hits "Enter"
  63                                  while typing. They must be explicitly selected to
  64                                  be activated, but unlike InformationalMatch cause
  65                                  an action to be triggered. */
  66             ExactMatch = 100 /**< An exact match to the query */
  67         };
  68
  69         /**
  70          * Constructs a PossibleMatch associated with a given RunnerContext
  71          * and runner.
  72          *
  73          * @arg search the RunnerContext this match belongs to
  74          * @arg runner the runner this match belongs to
  75          */
  76         explicit QueryMatch(AbstractRunner *runner);
  77
  78         /**
  79          * Copy constructor
  80          */
  81         QueryMatch(const QueryMatch &other);
  82
  83         ~QueryMatch();
  84
  85         bool isValid() const;
  86
  87         /**
  88          * Sets the type of match this action represents.
  89          */
  90         void setType(Type type);
  91
  92         /**
  93          * The type of action this is. Defaults to PossibleMatch.
  94          */
  95         Type type() const;
  96
  97         /**
  98          * Sets the relevance of this action for the search
  99          * it was created for.
 100          *
 101          * @param relevance a number between 0 and 1.
 102          */
 103         void setRelevance(qreal relevance);
 104
 105         /**
 106          * The relevance of this action to the search. By default,
 107          * the relevance is 1.
 108          *
 109          * @return a number between 0 and 1
 110          */
 111         qreal relevance() const;
 112
 113         /**
 114          * The runner associated with this action
 115          */
 116         AbstractRunner *runner() const;
 117
 118         /**
 119          * A string that can be used as an ID for this match,
 120          * even between different queries. It is based in part
 121          * on the source of the match (the AbstractRunner) and
 122          * distinguishing information provided by the runner,
 123          * ensuring global uniqueness as well as consistency
 124          * between query matches.
 125          */
 126         QString id() const;
 127
 128         QString text() const;
 129         QString subtext() const;
 130         QVariant data() const;
 131         QIcon icon() const;
 132         bool isEnabled() const;
 133
 134         bool operator<(const QueryMatch &other) const;
 135         QueryMatch &operator=(const QueryMatch &other);
 136
 137         /**
 138          * Requests this match to activae using the given context
 139          *
 140          * @param context the context to use in conjunction with this run
 141          *
 142          * @sa AbstractRunner::run
 143          */
 144         void run(const RunnerContext &context) const;
 145
 146         /**
 147          * Sets data to be used internally by the associated
 148          * AbstractRunner.
 149          *
 150          * When set, it is also used to form
 151          * part of the id() for this match. If that is innapropriate
 152          * as an id, the runner may generate its own id and set that
 153          * with setId(const QString&) directly after calling setData
 154          */
 155         void setData(const QVariant &data);
 156
 157         /**
 158          * Sets the id for this match; useful if the id does not
 159          * match data().toString(). The id must be unique to all
 160          * matches from this runner, and should remain constant
 161          * for the same query for best results.
 162          *
 163          * @param id the new identifying string to use to refer
 164          *           to this entry
 165          */
 166         void setId(const QString &id);
 167
 168         void setText(const QString &text);
 169         void setSubtext(const QString &text);
 170         void setIcon(const QIcon &icon);
 171         void setEnabled(bool enable);
 172
 173         /**
 174          * The current action.
 175          */
 176         QAction* selectedAction() const;
 177         /**
 178         * Sets the selected action
 179         */
 180         void setSelectedAction(QAction *action);
 181
 182     private:
 183         QSharedDataPointer<QueryMatchPrivate> d;
 184 };
 185
 186 }
 187
 188 #endif