src/plugins/locator/ilocatorfilter.h

   1 /**************************************************************************
   2 **
   3 ** This file is part of Qt Creator
   4 **
   5 ** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
   6 **
   7 ** Contact: Nokia Corporation (qt-info@nokia.com)
   8 **
   9 ** No Commercial Usage
  10 **
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 **
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Nokia gives you certain additional
  26 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** If you have questions regarding the use of this file, please contact
  30 ** Nokia at qt-info@nokia.com.
  31 **
  32 **************************************************************************/
  33
  34 #ifndef ILOCATORFILTER_H
  35 #define ILOCATORFILTER_H
  36
  37 #include "locator_global.h"
  38
  39 #include <QtCore/QVariant>
  40 #include <QtCore/QFutureInterface>
  41 #include <QtGui/QIcon>
  42
  43 namespace Locator {
  44
  45 class ILocatorFilter;
  46
  47 struct FilterEntry
  48 {
  49     FilterEntry()
  50         : filter(0)
  51         , resolveFileIcon(false)
  52     {}
  53
  54     FilterEntry(ILocatorFilter *fromFilter, const QString &name, const QVariant &data,
  55                 const QIcon &icon = QIcon())
  56         : filter(fromFilter)
  57         , displayName(name)
  58         , internalData(data)
  59         , displayIcon(icon)
  60         , resolveFileIcon(false)
  61     {}
  62
  63     bool operator==(const FilterEntry &other) const {
  64         if (internalData.canConvert(QVariant::String))
  65             return (internalData.toString() == other.internalData.toString());
  66         return internalData.constData() == other.internalData.constData();
  67     }
  68
  69     /* backpointer to creating filter */
  70     ILocatorFilter *filter;
  71     /* displayed string */
  72     QString displayName;
  73     /* extra information displayed in light-gray in a second column (optional) */
  74     QString extraInfo;
  75     /* can be used by the filter to save more information about the entry */
  76     QVariant internalData;
  77     /* icon to display along with the entry */
  78     QIcon displayIcon;
  79     /* internal data is interpreted as file name and icon is retrieved from the file system if true */
  80     bool resolveFileIcon;
  81 };
  82
  83 class LOCATOR_EXPORT ILocatorFilter : public QObject
  84 {
  85     Q_OBJECT
  86
  87 public:
  88     enum Priority {High = 0, Medium = 1, Low = 2};
  89
  90     ILocatorFilter(QObject *parent = 0);
  91     virtual ~ILocatorFilter() {}
  92
  93     /* Visible name. */
  94     virtual QString displayName() const = 0;
  95
  96     /* Internal name. */
  97     virtual QString id() const = 0;
  98
  99     /* Selection list order in case of multiple active filters (high goes on top). */
 100     virtual Priority priority() const = 0;
 101
 102     /* String to type to use this filter exclusively. */
 103     QString shortcutString() const;
 104
 105     /* List of matches for the given user entry. */
 106     virtual QList<FilterEntry> matchesFor(QFutureInterface<Locator::FilterEntry> &future, const QString &entry) = 0;
 107
 108     /* User has selected the given entry that belongs to this filter. */
 109     virtual void accept(FilterEntry selection) const = 0;
 110
 111     /* Implement to update caches on user request, if that's a long operation. */
 112     virtual void refresh(QFutureInterface<void> &future) = 0;
 113
 114     /* Saved state is used to restore the filter at start up. */
 115     virtual QByteArray saveState() const;
 116
 117     /* Used to restore the filter at start up. */
 118     virtual bool restoreState(const QByteArray &state);
 119
 120     /* User wants to configure this filter (if supported). Use it to pop up a dialog.
 121      * needsRefresh is used as a hint to indicate that refresh should be called.
 122      * The default implementation allows changing the shortcut and whether the filter
 123      * is enabled by default.
 124      */
 125     virtual bool openConfigDialog(QWidget *parent, bool &needsRefresh);
 126
 127     /* If there is a configure dialog available for this filter. The default
 128      * implementation returns true. */
 129     virtual bool isConfigurable() const;
 130
 131     /* Is this filter used also when the shortcutString is not used? */
 132     bool isIncludedByDefault() const;
 133
 134     /* Returns whether the filter should be hidden from configuration and menus. */
 135     bool isHidden() const;
 136
 137     static QString trimWildcards(const QString &str) {
 138         if (str.isEmpty())
 139             return str;
 140         int first = 0, last = str.size()-1;
 141         while (first < str.size() && (str.at(first) == '*' || str.at(first) == '?'))
 142             ++first;
 143         while (last >= 0 && (str.at(last) == '*' || str.at(last) == '?'))
 144             --last;
 145         if (first > last)
 146             return QString();
 147         return str.mid(first, last-first+1);
 148     }
 149
 150 protected:
 151     void setShortcutString(const QString &shortcut);
 152     void setIncludedByDefault(bool includedByDefault);
 153     void setHidden(bool hidden);
 154
 155 private:
 156     QString m_shortcut;
 157     bool m_includedByDefault;
 158     bool m_hidden;
 159 };
 160
 161 } // namespace Locator
 162
 163 #endif // ILOCATORFILTER_H