KTextEditor

codecompletionmodelcontrollerinterface.h
1 /*
2  SPDX-FileCopyrightText: 2008 Niko Sams <[email protected]>
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 
14 class QModelIndex;
15 
16 namespace KTextEditor
17 {
18 class 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 <[email protected]>
58  * \author Joseph Wenninger
59  */
61 {
62 public:
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 
180 Q_DECLARE_INTERFACE(KTextEditor::CodeCompletionModelControllerInterface, "org.kde.KTextEditor.CodeCompletionModelControllerInterface")
181 
182 #endif // KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H
An object representing a section of text, from one Cursor to another.
The Cursor represents a position in a Document.
Definition: cursor.h:71
A text widget with KXMLGUIClient that represents a Document.
Definition: view.h:146
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 03:50:21 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.