KTextEditor

codecompletionmodelcontrollerinterface.h
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 CodeCompletionModelControllerInterface codecompletionmodelcontrollerinterface.h <KTextEditor/CodeCompletionModelControllerInterface>
22 *
23 * \short Controller interface for a CodeCompletionModel
24 *
25 * \ingroup kte_group_ccmodel_extensions
26 *
27 * The CodeCompletionModelControllerInterface gives an CodeCompletionModel better
28 * control over the completion.
29 *
30 * By implementing methods defined in this interface you can:
31 * - control when automatic completion should start (shouldStartCompletion())
32 * - define a custom completion range (that will be replaced when the completion
33 * is executed) (completionRange())
34 * - dynamically modify the completion range during completion (updateCompletionRange())
35 * - specify the string used for filtering the completion (filterString())
36 * - control when completion should stop (shouldAbortCompletion())
37 *
38 * When the interface is not implemented, or no methods are overridden the
39 * default behaviour is used, which will be correct in many situations.
40 *
41 *
42 * \section ccmodelcontroller_impl Implementing the Interface
43 * To use this class implement it in your CodeCompletionModel.
44 *
45 * \code
46 * class MyCodeCompletion : public KTextEditor::CodeCompletionTestModel,
47 public KTextEditor::CodeCompletionModelControllerInterface
48 * {
49 * Q_OBJECT
50 * Q_INTERFACES(KTextEditor::CodeCompletionModelControllerInterface)
51 * public:
52 * KTextEditor::Range completionRange(KTextEditor::View* view, const KTextEditor::Cursor &position);
53 * };
54 * \endcode
55 *
56 * \see CodeCompletionModel
57 * \author Niko Sams <niko.sams@gmail.com>
58 * \author Joseph Wenninger
59 */
61{
62public:
65
66 /**
67 * This function decides if the automatic completion should be started when
68 * the user entered some text.
69 *
70 * The default implementation will return true if the last character in
71 * \p insertedText is a letter, a number, '.', '_' or '>'
72 *
73 * \param view The view to generate completions for
74 * \param insertedText The text that was inserted by the user
75 * \param userInsertion Whether the text was inserted by the user using typing.
76 * If false, it may have been inserted for example by code-completion.
77 * \param position Current cursor position
78 * \return \e true, if the completion should be started, otherwise \e false
79 */
80 virtual bool shouldStartCompletion(View *view, const QString &insertedText, bool userInsertion, const Cursor &position);
81
82 /**
83 * This function returns the completion range that will be used for the
84 * current completion.
85 *
86 * This range will be used for filtering the completion list and will get
87 * replaced when executing the completion
88 *
89 * The default implementation will work for most languages that don't have
90 * special chars in identifiers. Since 5.83 the default implementation takes
91 * into account the wordCompletionRemoveTail configuration option, if that
92 * option is enabled the whole word the cursor is inside is replaced with the
93 * completion, however if it's disabled only the text on the left of the cursor
94 * will be replaced with the completion.
95 *
96 * \param view The view to generate completions for
97 * \param position Current cursor position
98 * \return the completion range
99 */
100 virtual Range completionRange(View *view, const Cursor &position);
101
102 /**
103 * This function lets the CompletionModel dynamically modify the range.
104 * Called after every change to the range (eg. when user entered text)
105 *
106 * The default implementation does nothing.
107 *
108 * \param view The view to generate completions for
109 * \param range Reference to the current range
110 * \returns the modified range
111 */
112 virtual Range updateCompletionRange(View *view, const Range &range);
113
114 /**
115 * This function returns the filter-text used for the current completion.
116 * Can return an empty string to disable filtering.
117 *
118 * The default implementation will return the text from \p range start to
119 * the cursor \p position.
120 *
121 * \param view The view to generate completions for
122 * \param range The completion range
123 * \param position Current cursor position
124 * \return the string used for filtering the completion list
125 */
126 virtual QString filterString(View *view, const Range &range, const Cursor &position);
127
128 /**
129 * This function decides if the completion should be aborted.
130 * Called after every change to the range (eg. when user entered text)
131 *
132 * The default implementation will return true when any special character was entered, or when the range is empty.
133 *
134 * \param view The view to generate completions for
135 * \param range The completion range
136 * \param currentCompletion The text typed so far
137 * \return \e true, if the completion should be aborted, otherwise \e false
138 */
139 virtual bool shouldAbortCompletion(View *view, const Range &range, const QString &currentCompletion);
140
141 /**
142 * When an item within this model is currently selected in the completion-list, and the user inserted the given character,
143 * should the completion-item be executed? This can be used to execute items from other inputs than the return-key.
144 * For example a function item could be executed by typing '(', or variable items by typing '.'.
145 * \param selected The currently selected index
146 * \param inserted The character that was inserted by tue user
147 */
148 virtual bool shouldExecute(const QModelIndex &selected, QChar inserted);
149
150 /**
151 * Notification that completion for this model has been aborted.
152 * \param view The view in which the completion for this model was aborted
153 */
154 virtual void aborted(View *view);
155
157 None = 0,
158 HideListIfAutomaticInvocation = 1, /** If this is returned, the completion-list is hidden if it was invoked automatically */
159 ForExtension = 0xffff
160 };
161
162 /**
163 * Called whenever an item in the completion-list perfectly matches the current filter text.
164 * \param matched The index that is matched
165 * \return Whether the completion-list should be hidden on this event. The default-implementation always returns HideListIfAutomaticInvocation
166 */
167 virtual MatchReaction matchingItem(const QModelIndex &matched);
168
169 /**
170 * When multiple completion models are used at the same time, it may happen that multiple models add items with the same
171 * name to the list. This option allows to hide items from this completion model when another model with higher priority
172 * contains items with the same name.
173 * \return Whether items of this completion model should be hidden if another completion model has items with the same name
174 */
175 virtual bool shouldHideItemsWithEqualNames() const;
176};
177
178}
179
180Q_DECLARE_INTERFACE(KTextEditor::CodeCompletionModelControllerInterface, "org.kde.KTextEditor.CodeCompletionModelControllerInterface")
181
182#endif // KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H
The Cursor represents a position in a Document.
Definition cursor.h:75
An object representing a section of text, from one Cursor to another.
A text widget with KXMLGUIClient that represents a Document.
Definition view.h:244
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:42:02 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.