src/plugins/texteditor/icompletioncollector.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 COMPLETIONCOLLECTORINTERFACE_H
  35 #define COMPLETIONCOLLECTORINTERFACE_H
  36
  37 #include "texteditor_global.h"
  38
  39 #include <QtCore/QObject>
  40 #include <QtCore/QVariant>
  41 #include <QtGui/QIcon>
  42
  43 namespace TextEditor {
  44
  45 namespace Internal {
  46 class ICompletionCollectorPrivate;
  47 }
  48
  49 class ICompletionCollector;
  50 class ITextEditor;
  51 class CompletionSettings;
  52
  53 enum CompletionPolicy
  54 {
  55     QuickFixCompletion, // Used for "Quick Fix" operation.
  56     TextCompletion,     // Plain word completion.
  57     SemanticCompletion  // Completion using code models.
  58 };
  59
  60 class CompletionItem
  61 {
  62 public:
  63     CompletionItem(ICompletionCollector *collector = 0)
  64         : duplicateCount(0),
  65           order(0),
  66           originalIndex(0),
  67           collector(collector),
  68           isSnippet(false)
  69     { }
  70
  71     bool isValid() const
  72     { return collector != 0; }
  73
  74     QString text;
  75     QString details;
  76     QIcon icon;
  77     QVariant data;
  78     int duplicateCount;
  79     int order;
  80     int originalIndex;
  81     ICompletionCollector *collector;
  82     bool isSnippet;
  83 };
  84
  85 /* Defines the interface to completion collectors. A completion collector tells
  86  * the completion support code when a completion is triggered and provides the
  87  * list of possible completions. It keeps an internal state so that it can be
  88  * polled for the list of completions, which is reset with a call to reset.
  89  */
  90 class TEXTEDITOR_EXPORT ICompletionCollector : public QObject
  91 {
  92     Q_OBJECT
  93 public:
  94     ICompletionCollector(QObject *parent = 0);
  95     virtual ~ICompletionCollector();
  96
  97     const CompletionSettings &completionSettings() const;
  98
  99     virtual QList<CompletionItem> getCompletions();
 100     virtual bool shouldRestartCompletion();
 101
 102     /* Returns the current active ITextEditor */
 103     virtual ITextEditor *editor() const = 0;
 104     virtual int startPosition() const = 0;
 105
 106     /*
 107      * Returns true if this completion collector can be used with the given editor.
 108      */
 109     virtual bool supportsEditor(ITextEditor *editor) const = 0;
 110
 111     /*
 112      * Returns true if this completion collector supports the given completion policy.
 113      */
 114     virtual bool supportsPolicy(CompletionPolicy policy) const = 0;
 115
 116     /* This method should return whether the cursor is at a position which could
 117      * trigger an autocomplete. It will be called each time a character is typed in
 118      * the text editor.
 119      */
 120     virtual bool triggersCompletion(ITextEditor *editor) = 0;
 121
 122     // returns starting position
 123     virtual int startCompletion(ITextEditor *editor) = 0;
 124
 125     /* This method should add all the completions it wants to show into the list,
 126      * based on the given cursor position.
 127      */
 128     virtual void completions(QList<CompletionItem> *completions) = 0;
 129
 130     /**
 131      * This method should return true when the given typed character should cause
 132      * the selected completion item to be completed.
 133      */
 134     virtual bool typedCharCompletes(const CompletionItem &item, QChar typedChar) = 0;
 135
 136     /**
 137      * This method should complete the given completion item.
 138      *
 139      * \param typedChar Non-null when completion was triggered by typing a
 140      *                  character. Possible values depend on typedCharCompletes()
 141      */
 142     virtual void complete(const CompletionItem &item, QChar typedChar) = 0;
 143
 144     /* This method gives the completion collector a chance to partially complete
 145      * based on a set of items. The general use case is to complete the common
 146      * prefix shared by all possible completion items.
 147      *
 148      * Returns whether the completion popup should be closed.
 149      */
 150     virtual bool partiallyComplete(const QList<TextEditor::CompletionItem> &completionItems);
 151
 152     virtual void sortCompletion(QList<TextEditor::CompletionItem> &completionItems);
 153
 154     /* Called when it's safe to clean up the completion items.
 155      */
 156     virtual void cleanup() = 0;
 157
 158     // helpers
 159
 160     void filter(const QList<TextEditor::CompletionItem> &items,
 161                 QList<TextEditor::CompletionItem> *filteredItems,
 162                 const QString &key);
 163
 164 public slots:
 165     void setCompletionSettings(const TextEditor::CompletionSettings &);
 166
 167 protected:
 168     static bool compareChar(const QChar &item, const QChar &other);
 169     static bool lessThan(const QString &item, const QString &other);
 170     static bool completionItemLessThan(const CompletionItem &item, const CompletionItem &other);
 171
 172 private:
 173     Internal::ICompletionCollectorPrivate *m_d;
 174 };
 175
 176 class TEXTEDITOR_EXPORT IQuickFixCollector : public ICompletionCollector
 177 {
 178     Q_OBJECT
 179
 180 public:
 181     IQuickFixCollector(QObject *parent = 0) : ICompletionCollector(parent) {}
 182     virtual ~IQuickFixCollector() {}
 183
 184     virtual bool typedCharCompletes(const CompletionItem &, QChar)
 185     { return false; }
 186
 187     virtual void fix(const TextEditor::CompletionItem &item) = 0;
 188
 189     virtual void complete(const CompletionItem &item, QChar typedChar)
 190     {
 191         Q_UNUSED(typedChar)
 192         fix(item);
 193     }
 194
 195     virtual bool triggersCompletion(TextEditor::ITextEditor *)
 196     { return false; }
 197
 198     virtual bool partiallyComplete(const QList<TextEditor::CompletionItem> &)
 199     { return false; }
 200 };
 201
 202
 203 } // namespace TextEditor
 204
 205 #endif // COMPLETIONCOLLECTORINTERFACE_H