KTextEditor

codecompletioninterface.h
1 /*
2  SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef KTEXTEDITOR_CODECOMPLETIONINTERFACE_H
8 #define KTEXTEDITOR_CODECOMPLETIONINTERFACE_H
9 
10 #include <QObject>
11 #include <ktexteditor/codecompletionmodel.h>
12 #include <ktexteditor/range.h>
13 #include <ktexteditor_export.h>
14 
15 namespace KTextEditor
16 {
17 class CodeCompletionModel;
18 
19 /**
20  * \class CodeCompletionInterface codecompletioninterface.h <KTextEditor/CodeCompletionInterface>
21  *
22  * \brief Code completion extension interface for the View.
23  *
24  * \ingroup kte_group_view_extensions
25  *
26  * \section compiface_intro Introduction
27  *
28  * The CodeCompletionInterface is designed to provide code completion
29  * functionality for a KTextEditor::View. This interface provides the basic
30  * mechanisms to display a list of completions, update this list according
31  * to user input, and allow the user to select a completion.
32  *
33  * Essentially, this provides an item view for the available completions. In
34  * order to use this interface, you will need to implement a
35  * CodeCompletionModel that generates the relevant completions given the
36  * current input.
37  *
38  * \section compiface_access Accessing the CodeCompletionInterface
39  *
40  * The CodeCompletionInterface is an extension interface for a
41  * View, i.e. the View inherits the interface \e provided that the
42  * used KTextEditor library implements the interface. Use qobject_cast to
43  * access the interface:
44  * \code
45  * // view is of type KTextEditor::View*
46  * auto iface = qobject_cast<KTextEditor::CodeCompletionInterface*>(view);
47  *
48  * if (iface) {
49  * // the implementation supports the interface
50  * // do stuff
51  * } else {
52  * // the implementation does not support the interface
53  * }
54  * \endcode
55  *
56  * \section compiface_usage Using the CodeCompletionInterface
57  *
58  * The CodeCompletionInterface can be used in different ways, which we
59  * will call "automatic", and "manual".
60  *
61  * \subsection compiface_automatic Automatic
62  *
63  * In automatic mode, the CodeCompletionInterface will take care of
64  * starting and aborting the generation of code completions as
65  * appropriate, when the users inserts or changes text.
66  *
67  * To use the interface in this way, first register a CodeCompletionModel
68  * using registerCompletionModel(). Now call setAutomaticCompletionEnabled()
69  * to enabled automatic completions.
70  *
71  * \subsection compiface_manual Manual
72  *
73  * If you need more control over when code completions get shown or not,
74  * or which fragment of the text should be considered as the basis for
75  * generated completions, proceed as follows:
76  *
77  * Call setAutomaticCompletionEnabled(false) to disable automatic
78  * completions. To start the generation of code completions for the current
79  * word, call startCompletion(), with the appropriate parameters. To hide the
80  * generated completions, use abortCompletion().
81  *
82  * \see KTextEditor::View, KTextEditor::CodeCompletionModel
83  */
84 class KTEXTEDITOR_EXPORT CodeCompletionInterface
85 {
86 public:
87  virtual ~CodeCompletionInterface();
88 
89  /**
90  * Query whether the code completion box is currently displayed.
91  */
92  virtual bool isCompletionActive() const = 0;
93 
94  /**
95  * Invoke code completion over a given range, with a specific \a model.
96  */
97  virtual void startCompletion(const Range &word, CodeCompletionModel *model) = 0;
98 
99  /**
100  * Abort the currently displayed code completion without executing any currently
101  * selected completion. This is safe, even when the completion box is not currently
102  * active.
103  * \see isCompletionActive()
104  */
105  virtual void abortCompletion() = 0;
106 
107  /**
108  * Force execution of the currently selected completion, and hide the code completion
109  * box.
110  */
111  virtual void forceCompletion() = 0;
112 
113  /**
114  * Register a new code completion \p model.
115  * \param model new completion model
116  * \see unregisterCompletionModel()
117  */
118  virtual void registerCompletionModel(CodeCompletionModel *model) = 0;
119 
120  /**
121  * Unregister a code completion \p model.
122  * \param model the model that should be unregistered
123  * \see registerCompletionModel()
124  */
125  virtual void unregisterCompletionModel(CodeCompletionModel *model) = 0;
126 
127  /**
128  * Determine the status of automatic code completion invocation.
129  */
130  virtual bool isAutomaticInvocationEnabled() const = 0;
131 
132  /**
133  * Enable or disable automatic code completion invocation.
134  */
135  virtual void setAutomaticInvocationEnabled(bool enabled = true) = 0;
136 
137  // Q_SIGNALS:
138  // void completionExecuted(KTextEditor::View* view, const KTextEditor::Cursor& position, KTextEditor::CodeCompletionModel* model, int row);
139  // void completionAborted(KTextEditor::View* view);
140 };
141 
142 /**
143  * \class CodeCompletionInterfaceV2 codecompletioninterface.h <KTextEditor/CodeCompletionInterface>
144  *
145  * \brief Code completion extension interface for the View, version 2.
146  *
147  * \ingroup kte_group_view_extensions
148  *
149  * \section compifacev2_intro Introduction
150  *
151  * The CodeCompletionInterfaceV2 is an extended version of the CodeCompletionInterface.
152  * Refer to the base CodeCompletionInterface for a more detailed description.
153  *
154  * \section compifacev2_access Accessing the CodeCompletionInterfaceV2
155  *
156  * The CodeCompletionInterfaceV2 is an extension interface for a
157  * View, i.e. the View inherits the interface \e provided that the
158  * used KTextEditor library implements the interface. Use qobject_cast to
159  * access the interface:
160  * \code
161  * // view is of type KTextEditor::View*
162  * auto iface = qobject_cast<KTextEditor::CodeCompletionInterfaceV2*>(view);
163  *
164  * if (iface) {
165  * // the implementation supports the interface
166  * // do stuff
167  * } else {
168  * // the implementation does not support the interface
169  * }
170  * \endcode
171  *
172  * \since 5.74
173  */
174 class KTEXTEDITOR_EXPORT CodeCompletionInterfaceV2 : public CodeCompletionInterface
175 {
176  // KF6: Merge KTextEditor::CodeCompletionInterfaceV2 into KTextEditor::CodeCompletionInterface
177 public:
178  ~CodeCompletionInterfaceV2() override;
179  /**
180  * Invoke code completion over a given range, with specific models and invocation type.
181  * \param models list of models to start. If this is an empty list, all registered models are started.
182  */
183  virtual void startCompletion(const Range &word,
185  CodeCompletionModel::InvocationType invocationType = CodeCompletionModel::ManualInvocation) = 0;
187 
188  /**
189  * Obtain the list of registered code completion models.
190  * \returns a list of a models that are currently registered
191  * \see registerCompletionModel(CodeCompletionModel*)
192  */
193  virtual QList<CodeCompletionModel *> codeCompletionModels() const = 0;
194 };
195 
196 }
197 
198 Q_DECLARE_INTERFACE(KTextEditor::CodeCompletionInterface, "org.kde.KTextEditor.CodeCompletionInterface")
199 Q_DECLARE_INTERFACE(KTextEditor::CodeCompletionInterfaceV2, "org.kde.KTextEditor.CodeCompletionInterfaceV2")
200 
201 #endif // KTEXTEDITOR_CODECOMPLETIONINTERFACE_H
Code completion extension interface for the View, version 2.
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
An object representing a section of text, from one Cursor to another.
Code completion extension interface for the View.
virtual void startCompletion(const Range &word, CodeCompletionModel *model)=0
Invoke code completion over a given range, with a specific model.
An item model for providing code completion, and meta information for enhanced presentation.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Jan 20 2022 22:50:38 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.