KCompletion

kcompletionbase.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 1999, 2000 Carsten Pfeiffer <[email protected]>
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 
17 class 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 <[email protected]>
34  */
35 
36 class KCOMPLETION_EXPORT KCompletionBase
37 {
38 public:
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  */
46  /**
47  * Text completion (by default Ctrl-E).
48  */
50  /**
51  * Switch to previous completion (by default Ctrl-Up).
52  */
54  /**
55  * Switch to next completion (by default Ctrl-Down).
56  */
58  /**
59  * Substring completion (by default Ctrl-T).
60  */
62  };
63 
64  // Map for the key binding types mentioned above.
66 
67  /**
68  * Default constructor.
69  */
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 #if KCOMPLETION_ENABLE_DEPRECATED_SINCE(5, 0)
254  /**
255  * @deprecated since 5.0, use keyBinding instead
256  */
257  KCOMPLETION_DEPRECATED_VERSION(5, 0, "Use KCompletionBase::keyBinding(KeyBindingType)")
258  QList<QKeySequence> getKeyBinding(KeyBindingType item) const
259  {
260  return keyBinding(item);
261  }
262 #endif
263 
264  /**
265  * Sets this object to use global values for key bindings.
266  *
267  * This method changes the values of the key bindings for
268  * rotation and completion features to the default values
269  * provided in KGlobalSettings.
270  *
271  * NOTE: By default, inheriting widgets should use the
272  * global key bindings so that there is no need to
273  * call this method.
274  */
275  void useGlobalKeyBindings();
276 
277  /**
278  * A pure virtual function that must be implemented by
279  * all inheriting classes.
280  *
281  * This function is intended to allow external completion
282  * implementations to set completed text appropriately. It
283  * is mostly relevant when the completion mode is set to
284  * CompletionAuto and CompletionManual modes. See
285  * KCompletionBase::setCompletedText.
286  * Does nothing in CompletionPopup mode, as all available
287  * matches will be shown in the popup.
288  *
289  * @param text the completed text to be set in the widget.
290  */
291  virtual void setCompletedText(const QString &text) = 0;
292 
293  /**
294  * A pure virtual function that must be implemented by
295  * all inheriting classes.
296  * @param items the list of completed items
297  * @param autoSuggest if @c true, the first element of @p items
298  * is automatically completed (i.e. preselected).
299  */
300  virtual void setCompletedItems(const QStringList &items, bool autoSuggest = true) = 0;
301 
302  /**
303  * Returns a pointer to the completion object.
304  *
305  * This method is only different from completionObject()
306  * in that it does not create a new KCompletion object even if
307  * the internal pointer is @c NULL. Use this method to get the
308  * pointer to a completion object when inheriting so that you
309  * will not inadvertently create it.
310  *
311  * @return the completion object or @c NULL if one does not exist.
312  */
313  KCompletion *compObj() const;
314 
315 protected:
316  /**
317  * Returns a key binding map.
318  *
319  * This method is the same as getKeyBinding(), except that it
320  * returns the whole keymap containing the key bindings.
321  *
322  * @return the key binding used for the feature given by @p item.
323  * @since 5.0
324  */
325  KeyBindingMap keyBindingMap() const;
326 
327 #if KCOMPLETION_ENABLE_DEPRECATED_SINCE(5, 0)
328  /**
329  * @deprecated since 5.0, use keyBindingMap instead
330  */
331  KCOMPLETION_DEPRECATED_VERSION(5, 0, "Use KCompletionBase::keyBindingMap()")
332  KeyBindingMap getKeyBindings() const
333  {
334  return keyBindingMap();
335  }
336 #endif
337 
338  /**
339  * Sets the keymap.
340  *
341  * @param keyBindingMap
342  */
343  void setKeyBindingMap(KeyBindingMap keyBindingMap);
344 
345  /**
346  * Sets or removes the delegation object. If a delegation object is
347  * set, all function calls will be forwarded to the delegation object.
348  * @param delegate the delegation object, or @c nullptr to remove it
349  */
350  void setDelegate(KCompletionBase *delegate);
351 
352  /**
353  * Returns the delegation object.
354  * @return the delegation object, or @c nullptr if there is none
355  * @see setDelegate()
356  */
357  KCompletionBase *delegate() const;
358 
359  /** Virtual hook, used to add new "virtual" functions while maintaining
360  binary compatibility. Unused in this class.
361  */
362  virtual void virtual_hook(int id, void *data);
363 
364 private:
365  Q_DISABLE_COPY(KCompletionBase)
366  std::unique_ptr<KCompletionBasePrivate> const d_ptr;
367 };
368 
369 #endif // KCOMPLETIONBASE_H
Switch to next completion (by default Ctrl-Down).
Text completion (by default Ctrl-E).
Substring completion (by default Ctrl-T).
Switch to previous completion (by default Ctrl-Up).
CompletionMode
This enum describes the completion mode used for by the KCompletion class.
Definition: kcompletion.h:131
A generic class for completing QStrings.
Definition: kcompletion.h:117
An abstract base class for adding a completion feature into widgets.
KeyBindingType
Constants that represent the items whose shortcut key binding is programmable.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue Jan 25 2022 22:47:38 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.