1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 2005-2006 Hamish Rodda <rodda@kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License version 2 as published by the Free Software Foundation. |
7 | |
8 | This library is distributed in the hope that it will be useful, |
9 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
10 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
11 | Library General Public License for more details. |
12 | |
13 | You should have received a copy of the GNU Library General Public License |
14 | along with this library; see the file COPYING.LIB. If not, write to |
15 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
16 | Boston, MA 02110-1301, USA. |
17 | */ |
18 | |
19 | #ifndef KDELIBS_KTEXTEDITOR_CODECOMPLETIONINTERFACE_H |
20 | #define KDELIBS_KTEXTEDITOR_CODECOMPLETIONINTERFACE_H |
21 | |
22 | #include <ktexteditor/ktexteditor_export.h> |
23 | #include <QtCore/QObject> |
24 | #include <ktexteditor/range.h> |
25 | |
26 | namespace KTextEditor { |
27 | |
28 | class CodeCompletionModel; |
29 | |
30 | /** |
31 | * \brief Code completion extension interface for the View. |
32 | * |
33 | * \ingroup kte_group_view_extensions |
34 | * |
35 | * \section compiface_intro Introduction |
36 | * |
37 | * The CodeCompletionInterface is designed to provide code completion |
38 | * functionality for a KTextEditor::View. This interface provides the basic |
39 | * mechanisms to display a list of completions, update this list according |
40 | * to user input, and allow the user to select a completion. |
41 | * |
42 | * Essentially, this provides an item view for the available completions. In |
43 | * order to use this interface, you will need to implement a |
44 | * CodeCompletionModel that generates the relevant completions given the |
45 | * current input. |
46 | * |
47 | * \section compiface_access Accessing the CodeCompletionInterface |
48 | * |
49 | * The CodeCompletionInterface is an extension interface for a |
50 | * View, i.e. the View inherits the interface \e provided that the |
51 | * used KTextEditor library implements the interface. Use qobject_cast to |
52 | * access the interface: |
53 | * \code |
54 | * // view is of type KTextEditor::View* |
55 | * KTextEditor::CodeCompletionInterface *iface = |
56 | * qobject_cast<KTextEditor::CodeCompletionInterface*>( view ); |
57 | * |
58 | * if( iface ) { |
59 | * // the implementation supports the interface |
60 | * // do stuff |
61 | * } |
62 | * \endcode |
63 | * |
64 | * \section compiface_usage Using the CodeCompletionInterface |
65 | * |
66 | * The CodeCompletionInterface can be used in different ways, which we |
67 | * will call "automatic", and "manual". |
68 | * |
69 | * \subsection compiface_automatic Automatic |
70 | * |
71 | * In automatic mode, the CodeCompletionInterface will take care of |
72 | * starting and aborting the generation of code completions as |
73 | * appropriate, when the users inserts or changes text. |
74 | * |
75 | * To use the interface in this way, first register a CodeCompletionModel |
76 | * using registerCompletionModel(). Now call setAutomaticCompletionEnabled() |
77 | * to enabled automatic completions. |
78 | * |
79 | * \subsection compiface_manual Manual |
80 | * |
81 | * If you need more control over when code completions get shown or not, |
82 | * or which fragment of the text should be considered as the basis for |
83 | * generated completions, proceed as follows: |
84 | * |
85 | * Call setAutomaticCompletionEnabled(false) to disable automatic |
86 | * completions. To start the generation of code completions for the current |
87 | * word, call startCompletion(), with the appropriate parameters. To hide the |
88 | * generated completions, use abortCompletion(). |
89 | * |
90 | * \see KTextEditor::View, KTextEditor::CodeCompletionModel |
91 | */ |
92 | class KTEXTEDITOR_EXPORT CodeCompletionInterface |
93 | { |
94 | public: |
95 | virtual ~CodeCompletionInterface(); |
96 | |
97 | /** |
98 | * Query whether the code completion box is currently displayed. |
99 | */ |
100 | virtual bool isCompletionActive() const = 0; |
101 | |
102 | /** |
103 | * Invoke code completion over a given range, with a specific \a model. |
104 | */ |
105 | virtual void startCompletion(const Range& word, CodeCompletionModel* model) = 0; |
106 | |
107 | /** |
108 | * Abort the currently displayed code completion without executing any currently |
109 | * selected completion. This is safe, even when the completion box is not currently |
110 | * active. |
111 | * \see isCompletionActive() |
112 | */ |
113 | virtual void abortCompletion() = 0; |
114 | |
115 | /** |
116 | * Force execution of the currently selected completion, and hide the code completion |
117 | * box. |
118 | */ |
119 | virtual void forceCompletion() = 0; |
120 | |
121 | /** |
122 | * Register a new code completion \p model. |
123 | * \param model new completion model |
124 | * \see unregisterCompletionModel() |
125 | */ |
126 | virtual void registerCompletionModel(CodeCompletionModel* model) = 0; |
127 | |
128 | /** |
129 | * Unregister a code completion \p model. |
130 | * \param model the model that should be unregistered |
131 | * \see registerCompletionModel() |
132 | */ |
133 | virtual void unregisterCompletionModel(CodeCompletionModel* model) = 0; |
134 | |
135 | /** |
136 | * Determine the status of automatic code completion invocation. |
137 | */ |
138 | virtual bool isAutomaticInvocationEnabled() const = 0; |
139 | |
140 | /** |
141 | * Enable or disable automatic code completion invocation. |
142 | */ |
143 | virtual void setAutomaticInvocationEnabled(bool enabled = true) = 0; |
144 | |
145 | //signals: |
146 | //void completionExecuted(KTextEditor::View* view, const KTextEditor::Cursor& position, KTextEditor::CodeCompletionModel* model, int row); |
147 | //void completionAborted(KTextEditor::View* view); |
148 | }; |
149 | |
150 | } |
151 | |
152 | Q_DECLARE_INTERFACE(KTextEditor::CodeCompletionInterface, "org.kde.KTextEditor.CodeCompletionInterface" ) |
153 | |
154 | #endif // KDELIBS_KTEXTEDITOR_CODECOMPLETIONINTERFACE_H |
155 | |