1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999, 2000 Carsten Pfeiffer <pfeiffer@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KCOMPLETIONBASE_H
9#define KCOMPLETIONBASE_H
10
11#include <kcompletion.h>
12#include <kcompletion_export.h>
13
14#include <QMap>
15#include <memory>
16
17class KCompletionBasePrivate;
18
19/*!
20 * \class KCompletionBase
21 * \inmodule KCompletion
22 *
23 * \brief An abstract base class for adding a completion feature
24 * into widgets.
25 *
26 * This is a convenience class that provides the basic functions
27 * needed to add text completion support into widgets. All that
28 * is required is an implementation for the pure virtual function
29 * setCompletedText(). Refer to KLineEdit or KComboBox
30 * to see how easily such support can be added using this as a base
31 * class.
32 */
33
34class KCOMPLETION_EXPORT KCompletionBase
35{
36public:
37 Q_DECLARE_PRIVATE(KCompletionBase)
38 /*!
39 * Constants that represent the items whose shortcut
40 * key binding is programmable. The default key bindings
41 * for these items are defined in KStandardShortcut.
42 *
43 * \value TextCompletion Text completion (by default Ctrl-E).
44 * \value PrevCompletionMatch Switch to previous completion (by default Ctrl-Up).
45 * \value NextCompletionMatch Switch to next completion (by default Ctrl-Down).
46 * \value SubstringCompletion Substring completion (by default Ctrl-T).
47 */
48 enum KeyBindingType {
49 TextCompletion,
50 PrevCompletionMatch,
51 NextCompletionMatch,
52 SubstringCompletion,
53 };
54
55 /*!
56 * \typedef KCompletionBase::KeyBindingMap
57 * Map for the key binding types mentioned above.
58 */
59 typedef QMap<KeyBindingType, QList<QKeySequence>> KeyBindingMap;
60
61 /*!
62 * Default constructor.
63 */
64 KCompletionBase();
65
66 virtual ~KCompletionBase();
67
68 /*!
69 * Returns a pointer to the current completion object.
70 *
71 * If the completion object does not exist, it is automatically created and
72 * by default handles all the completion signals internally unless handleSignals
73 * is set to \c false. It is also automatically destroyed when the destructor
74 * is called. You can change this default behavior using the
75 * setAutoDeleteCompletionObject and setHandleSignals member
76 * functions.
77 *
78 * See also compObj.
79 *
80 * \a handleSignals if true, handles completion signals internally.
81 */
82 KCompletion *completionObject(bool handleSignals = true);
83
84 /*!
85 * Sets up the completion object to be used.
86 *
87 * This method assigns the completion object and sets it up to automatically
88 * handle the completion and rotation signals internally. You should use
89 * this function if you want to share one completion object among your
90 * widgets or need to use a customized completion object.
91 *
92 * The object assigned through this method is not deleted when this object's
93 * destructor is invoked unless you explicitly call setAutoDeleteCompletionObject
94 * after calling this method. Be sure to set the bool argument to false, if
95 * you want to handle the completion signals yourself.
96 *
97 * \a completionObject a KCompletion or a derived child object.
98 *
99 * \a handleCompletionSignals if \c true, handles completion signals internally.
100 */
101 virtual void setCompletionObject(KCompletion *completionObject, bool handleSignals = true);
102
103 /*!
104 * Enables this object to handle completion and rotation
105 * events internally.
106 *
107 * This function simply assigns a boolean value that
108 * indicates whether it should handle rotation and
109 * completion events or not. Note that this does not
110 * stop the object from emitting signals when these
111 * events occur.
112 *
113 * \a handle if true, it handles completion and rotation internally.
114 */
115 virtual void setHandleSignals(bool handle);
116
117 /*!
118 * Returns true if the completion object is deleted
119 * upon this widget's destruction.
120 *
121 * See setCompletionObject() and enableCompletion()
122 * for details.
123 *
124 * Returns \c true if the completion object will be deleted
125 * automatically
126 */
127 bool isCompletionObjectAutoDeleted() const;
128
129 /*!
130 * Sets the completion object when this widget's destructor
131 * is called.
132 *
133 * If the argument is set to \c true, the completion object
134 * is deleted when this widget's destructor is called.
135 *
136 * \a autoDelete if \c true, delete completion object on destruction.
137 */
138 void setAutoDeleteCompletionObject(bool autoDelete);
139
140 /*!
141 * Sets the widget's ability to emit text completion and
142 * rotation signals.
143 *
144 * Invoking this function with \a enable set to \c false will
145 * cause the completion and rotation signals not to be emitted.
146 * However, unlike setting the completion object to \c nullptr
147 * using setCompletionObject, disabling the emission of
148 * the signals through this method does not affect the current
149 * completion object.
150 *
151 * There is no need to invoke this function by default. When a
152 * completion object is created through completionObject or
153 * setCompletionObject, these signals are set to emit
154 * automatically. Also note that disabling this signals will not
155 * necessarily interfere with the objects' ability to handle these
156 * events internally. See setHandleSignals.
157 *
158 * \a enable if false, disables the emission of completion and rotation signals.
159 */
160 void setEnableSignals(bool enable);
161
162 /*!
163 * Returns \c true if the object handles the signals.
164 */
165 bool handleSignals() const;
166
167 /*!
168 * Returns \c true if the object emits the signals.
169 */
170 bool emitSignals() const;
171
172 /*!
173 * Sets whether the object emits rotation signals.
174 *
175 * \a emitRotationSignals if \c false, disables the emission of rotation signals.
176 */
177 void setEmitSignals(bool emitRotationSignals);
178
179 /*!
180 * Sets the type of completion to be used.
181 *
182 * \a mode Completion type
183 */
184 virtual void setCompletionMode(KCompletion::CompletionMode mode);
185
186 /*!
187 * Returns the current completion mode.
188 */
189 KCompletion::CompletionMode completionMode() const;
190
191 /*!
192 * Sets the key binding to be used for manual text
193 * completion, text rotation in a history list as
194 * well as a completion list.
195 *
196 *
197 * When the keys set by this function are pressed, a
198 * signal defined by the inheriting widget will be activated.
199 * If the default value or 0 is specified by the second
200 * parameter, then the key binding as defined in the global
201 * setting should be used. This method returns false
202 * when \a key is negative or the supplied key binding conflicts
203 * with another one set for another feature.
204 *
205 * \note To use a modifier key (Shift, Ctrl, Alt) as part of
206 * the key binding simply \a sum up the values of the
207 * modifier and the actual key. For example, to use CTRL+E, supply
208 * \c {"Qt::CtrlButton | Qt::Key_E"} as the second argument to this
209 * function.
210 *
211 * \a item the feature whose key binding needs to be set:
212 * \list
213 * \li TextCompletion the manual completion key binding.
214 * \li PrevCompletionMatch the previous match key for multiple completion.
215 * \li NextCompletionMatch the next match key for for multiple completion.
216 * \li SubstringCompletion the key for substring completion
217 * \endlist
218 *
219 * \a key key binding used to rotate down in a list.
220 *
221 * Returns \c true if key binding is successfully set.
222 * \sa keyBinding
223 */
224 bool setKeyBinding(KeyBindingType item, const QList<QKeySequence> &key);
225
226 /*!
227 * Returns the key binding used for the specified item.
228 *
229 * This method returns the key binding used to activate
230 * the feature given by \a item. If the binding
231 * contains modifier key(s), the sum of the modifier key
232 * and the actual key code is returned.
233 *
234 * \a item the item to check
235 *
236 * Returns the key binding used for the feature given by \a item.
237 *
238 * \sa setKeyBinding
239 *
240 * \since 5.0
241 */
242 QList<QKeySequence> keyBinding(KeyBindingType item) const;
243
244 /*!
245 * Sets this object to use global values for key bindings.
246 *
247 * This method changes the values of the key bindings for
248 * rotation and completion features to the default values
249 * provided in KGlobalSettings.
250 *
251 * \note By default, inheriting widgets should use the
252 * global key bindings so that there is no need to
253 * call this method.
254 */
255 void useGlobalKeyBindings();
256
257 /*!
258 * A pure virtual function that must be implemented by
259 * all inheriting classes.
260 *
261 * This function is intended to allow external completion
262 * implementations to set completed text appropriately. It
263 * is mostly relevant when the completion mode is set to
264 * CompletionAuto and CompletionManual modes. See
265 * KCompletionBase::setCompletedText.
266 * Does nothing in CompletionPopup mode, as all available
267 * matches will be shown in the popup.
268 *
269 * \a text the completed text to be set in the widget.
270 */
271 virtual void setCompletedText(const QString &text) = 0;
272
273 /*!
274 * A pure virtual function that must be implemented by
275 * all inheriting classes.
276 *
277 * \a items the list of completed items
278 *
279 * \a autoSuggest if \c true, the first element of \a items
280 * is automatically completed (i.e. preselected).
281 */
282 virtual void setCompletedItems(const QStringList &items, bool autoSuggest = true) = 0;
283
284 /*!
285 * Returns a pointer to the completion object.
286 *
287 * This method is only different from completionObject()
288 * in that it does not create a new KCompletion object even if
289 * the internal pointer is \c nullptr. Use this method to get the
290 * pointer to a completion object when inheriting so that you
291 * will not inadvertently create it.
292 *
293 * Returns the completion object or \c nullptr if one does not exist.
294 */
295 KCompletion *compObj() const;
296
297protected:
298 /*!
299 * Returns a key binding map.
300 *
301 * This method is the same as getKeyBinding(), except that it
302 * returns the whole keymap containing the key bindings.
303 *
304 * Returns the key binding used for the feature given by \a item.
305 * \since 5.0
306 */
307 KeyBindingMap keyBindingMap() const;
308
309 /*!
310 * Sets the keymap.
311 *
312 * \a keyBindingMap
313 */
314 void setKeyBindingMap(KeyBindingMap keyBindingMap);
315
316 /*!
317 * Sets or removes the delegation object. If a delegation object is
318 * set, all function calls will be forwarded to the delegation object.
319 * \a delegate the delegation object, or \c nullptr to remove it
320 */
321 void setDelegate(KCompletionBase *delegate);
322
323 /*!
324 * Returns the delegation object, or \c nullptr if there is none
325 * \sa setDelegate()
326 */
327 KCompletionBase *delegate() const;
328
329 virtual void virtual_hook(int id, void *data);
330
331private:
332 Q_DISABLE_COPY(KCompletionBase)
333 std::unique_ptr<KCompletionBasePrivate> const d_ptr;
334};
335
336#endif // KCOMPLETIONBASE_H
337

source code of kcompletion/src/kcompletionbase.h