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

source code of kcompletion/src/kcompletionbase.h