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
26namespace KTextEditor {
27
28class 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 */
92class 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
152Q_DECLARE_INTERFACE(KTextEditor::CodeCompletionInterface, "org.kde.KTextEditor.CodeCompletionInterface")
153
154#endif // KDELIBS_KTEXTEDITOR_CODECOMPLETIONINTERFACE_H
155