workspace/libs/plasma/searchcontext.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 SEARCHCONTEXT_H
  21 #define SEARCHCONTEXT_H
  22
  23 #include <QtCore/QList>
  24 #include <QtCore/QObject>
  25
  26 #include <plasma/plasma_export.h>
  27
  28 class KCompletion;
  29
  30 namespace Plasma
  31 {
  32
  33 class SearchMatch;
  34 class AbstractRunner;
  35
  36 /**
  37  * @short The SearchContext class provides information related to a search,
  38  *        including the search term, metadata on the search term and collected
  39  *        matches.
  40  */
  41 class PLASMA_EXPORT SearchContext : public QObject
  42 {
  43     Q_OBJECT
  44
  45     public:
  46         enum Type { UnknownType = 0,
  47                     Directory,
  48                     File,
  49                     NetworkLocation,
  50                     Executable,
  51                     ShellCommand,
  52                     Help
  53                   };
  54
  55         enum DataPolicy { Shared = 0,
  56                           SingleConsumer
  57                         };
  58
  59         explicit SearchContext(QObject *parent = 0, DataPolicy policy = Shared);
  60
  61         /**
  62          * Constructs a SearchContext with a DataPolicy of SingleConsumer that
  63          * contains the search metadata (though none of the currently registered
  64          * matches) from the passed in SearchContext. Primarily useful for creating
  65          * a thread-local copy of a Shared SearchContext.
  66          */
  67         SearchContext(QObject *parent, const SearchContext& other);
  68         ~SearchContext();
  69
  70
  71         /**
  72          * Sets the search term for this object and attempts to determine
  73          * the type of the search.
  74          * This clears all current matches in the process.
  75          */
  76         void resetSearchTerm(const QString&);
  77
  78         /**
  79          * Sets the search term for this object and attempts to determine
  80          * the type of the search.
  81          */
  82         void setSearchTerm(const QString&);
  83
  84         /**
  85          * @return the current search term.
  86          */
  87         QString searchTerm() const;
  88
  89         /**
  90          * The type of item the search term might refer to.
  91          * @see Type
  92          */
  93         Type type() const;
  94
  95         /**
  96          * The mimetype that the search term refers to, if discoverable.
  97          *
  98          * @return QString() if the mimetype can not be determined, otherwise
  99          *         the mimetype of the object being referred to by the search
 100          *         string.
 101          */
 102         QString mimetype() const;
 103
 104         /**
 105          * @return a completion object that can be used with UI elements
 106          */
 107         KCompletion* completionObject() const;
 108
 109         /**
 110          * Adds an item to the completion object.
 111          */
 112         void addStringCompletion(const QString& completion);
 113
 114         /**
 115          * Adds multiple items to the completion object.
 116          */
 117         void addStringCompletions(const QStringList& completions);
 118
 119         /**
 120          * Appends lists of matches to the list of matches.
 121          * The SearchContext takes over ownership of the matches on successful addition.
 122          *
 123          * This method is thread safe and causes the matchesChanged() signal to be emitted.
 124          *
 125          * @return true if matches were added, false if matches were e.g. outdated
 126          */
 127         bool addMatches(const QString& term, const QList<SearchMatch *> &matches);
 128
 129         /**
 130          * Appends a match to the existing list of matches.
 131          * The SearchContext takes over ownership of the match on successful addition.
 132          *
 133          * If you are going to be adding multiple matches, it is better to use
 134          * addMatches instead.
 135          *
 136          * @arg term the search term that this match was generated for
 137          * @arg match the match to add
 138          *
 139          * @return true if the match was added, false otherwise.
 140          */
 141         bool addMatch(const QString &term, SearchMatch *match);
 142
 143         /**
 144          * Takes the matches from this SearchContext and adds to them another.
 145          * If successful, the matches are removed from this SearchContext and
 146          * ownership passed to the other SearchContext
 147          *
 148          * @arg other the SearchContext to add this object's Matches to
 149          * @return true if matches were added, false if matches were e.g. outdated
 150          */
 151         bool addMatchesTo(SearchContext &other);
 152
 153         /**
 154          * Retrieves all available matches for the current search term.
 155          */
 156         QList<SearchMatch *> matches() const;
 157
 158         /**
 159          * Determines type of query
 160          */
 161         void determineType();
 162
 163         /**
 164          * Clears matches
 165          */
 166         void clearMatches();
 167
 168     Q_SIGNALS:
 169         void matchesChanged();
 170
 171     private:
 172         class Private;
 173         Private * const d;
 174 };
 175
 176 }
 177
 178 #endif