1/*
2 SPDX-FileCopyrightText: 2008 Niko Sams <niko.sams@gmail.com>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H
8#define KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H
9
10#include "codecompletionmodel.h"
11#include <ktexteditor/cursor.h>
12#include <ktexteditor_export.h>
13
14class QModelIndex;
15
16namespace KTextEditor
17{
18class View;
19
20/*!
21 * \class KTextEditor::CodeCompletionModelControllerInterface
22 * \inmodule KTextEditor
23 * \inheaderfile KTextEditor/CodeCompletionModelControllerInterface
24 *
25 * \brief Controller interface for a CodeCompletionModel instance.
26 *
27 * The CodeCompletionModelControllerInterface gives a CodeCompletionModel better
28 * control over the completion.
29 *
30 * By implementing methods defined in this interface you can:
31 * \list
32 * \li control when automatic completion should start - see shouldStartCompletion()
33 * \li define a custom completion range (that will be replaced when the completion
34 * is executed) - see completionRange()
35 * \li dynamically modify the completion range during completion -see updateCompletionRange()
36 * \li specify the string used for filtering the completion - see filterString()
37 * \li control when completion should stop - see shouldAbortCompletion()
38 * \endlist
39 *
40 * When the interface is not implemented, or no methods are overridden the
41 * default behaviour is used, which will be correct in many situations.
42 *
43 *
44 * Implementing the Interface
45 * To use this class implement it in your CodeCompletionModel.
46 *
47 * \code
48 * class MyCodeCompletion : public KTextEditor::CodeCompletionTestModel,
49 * public KTextEditor::CodeCompletionModelControllerInterface
50 * {
51 * Q_OBJECT
52 * Q_INTERFACES(KTextEditor::CodeCompletionModelControllerInterface)
53 * public:
54 * KTextEditor::Range completionRange(KTextEditor::View* view, const KTextEditor::Cursor &position);
55 * };
56 * \endcode
57 *
58 * \sa CodeCompletionModel
59 * \author Joseph Wenninger
60 * \ingroup kte_group_ccmodel_extensions
61 */
62class KTEXTEDITOR_EXPORT CodeCompletionModelControllerInterface
63{
64public:
65 /*!
66 *
67 */
68 CodeCompletionModelControllerInterface();
69 virtual ~CodeCompletionModelControllerInterface();
70
71 /*!
72 * This function decides if the automatic completion should be started when
73 * the user entered some text.
74 *
75 * The default implementation will return true if the last character in
76 *
77 * \a insertedText is a letter, a number, '.', '_' or '\>'
78 *
79 * \a view is the view to generate completions for
80 *
81 * \a insertedText is the text that was inserted by the user
82 *
83 * \a userInsertion is true if the text was inserted by the user using typing.
84 * If false, it may have been inserted for example by code-completion.
85 *
86 * \a position is the current cursor position
87 *
88 * Returns \e true, if the completion should be started, otherwise \e false
89 */
90 virtual bool shouldStartCompletion(View *view, const QString &insertedText, bool userInsertion, const Cursor &position);
91
92 /*!
93 * This function returns the completion range that will be used for the
94 * current completion.
95 *
96 * This range will be used for filtering the completion list and will get
97 * replaced when executing the completion
98 *
99 * The default implementation will work for most languages that don't have
100 * special chars in identifiers. Since 5.83 the default implementation takes
101 * into account the wordCompletionRemoveTail configuration option, if that
102 * option is enabled the whole word the cursor is inside is replaced with the
103 * completion, however if it's disabled only the text on the left of the cursor
104 * will be replaced with the completion.
105 *
106 * \a view is the view to generate completions for
107 *
108 * \a position is the current cursor position
109 *
110 * Returns the completion range
111 */
112 virtual Range completionRange(View *view, const Cursor &position);
113
114 /*!
115 * This function lets the CompletionModel dynamically modify the range.
116 * Called after every change to the range (eg. when user entered text)
117 *
118 * The default implementation does nothing.
119 *
120 * \a view is the view to generate completions for
121 *
122 * \a range are reference to the current range
123 *
124 * Returns the modified range
125 */
126 virtual Range updateCompletionRange(View *view, const Range &range);
127
128 /*!
129 * This function returns the filter-text used for the current completion.
130 * Can return an empty string to disable filtering.
131 *
132 * The default implementation will return the text from \a range start to
133 * the cursor \a position.
134 *
135 * \a view is the view to generate completions for
136 *
137 * \a range is the completion range
138 *
139 * \a position is the current cursor position
140 *
141 * Returns the string used for filtering the completion list
142 */
143 virtual QString filterString(View *view, const Range &range, const Cursor &position);
144
145 /*!
146 * This function decides if the completion should be aborted.
147 * Called after every change to the range (eg. when user entered text)
148 *
149 * The default implementation will return true when any special character was entered, or when the range is empty.
150 *
151 * \a view is the view to generate completions for
152 *
153 * \a range is the completion range
154 *
155 * \a currentCompletion is the text typed so far
156 *
157 * Returns \e true, if the completion should be aborted, otherwise \e false
158 */
159 virtual bool shouldAbortCompletion(View *view, const Range &range, const QString &currentCompletion);
160
161 /*!
162 * When an item within this model is currently selected in the completion-list, and the user inserted the given character,
163 * should the completion-item be executed? This can be used to execute items from other inputs than the return-key.
164 * For example a function item could be executed by typing '(', or variable items by typing '.'.
165 *
166 * \a selected is the currently selected index
167 *
168 * \a inserted is the character that was inserted by tue user
169 *
170 */
171 virtual bool shouldExecute(const QModelIndex &selected, QChar inserted);
172
173 /*!
174 * Notification that completion for this model has been aborted.
175 *
176 * \a view is the view in which the completion for this model was aborted
177 *
178 */
179 virtual void aborted(View *view);
180
181 /*!
182 \enum KTextEditor::CodeCompletionModelControllerInterface::MatchReaction
183
184 \value None
185 \value HideListIfAutomaticInvocation
186 If this is returned, the completion-list is hidden if it was invoked automatically
187 \value ForExtension
188 */
189 enum MatchReaction {
190 None = 0,
191 HideListIfAutomaticInvocation = 1,
192 ForExtension = 0xffff
193 };
194
195 /*!
196 * Called whenever an item in the completion-list perfectly matches the current filter text.
197 *
198 * \a matched is the index that is matched
199 *
200 * Returns Whether the completion-list should be hidden on this event. The default-implementation always returns HideListIfAutomaticInvocation
201 */
202 virtual MatchReaction matchingItem(const QModelIndex &matched);
203
204 /*!
205 * When multiple completion models are used at the same time, it may happen that multiple models add items with the same
206 * name to the list. This option allows to hide items from this completion model when another model with higher priority
207 * contains items with the same name.
208 * Returns Whether items of this completion model should be hidden if another completion model has items with the same name
209 */
210 virtual bool shouldHideItemsWithEqualNames() const;
211};
212
213}
214
215Q_DECLARE_INTERFACE(KTextEditor::CodeCompletionModelControllerInterface, "org.kde.KTextEditor.CodeCompletionModelControllerInterface")
216
217#endif // KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H
218

source code of ktexteditor/src/include/ktexteditor/codecompletionmodelcontrollerinterface.h