KCompletion

kcompletion.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 KCOMPLETION_H
9 #define KCOMPLETION_H
10 
11 #include <kcompletion_export.h>
12 
13 #include <QKeySequence>
14 #include <QObject>
15 #include <QPointer>
16 #include <QStringList>
17 #include <functional>
18 #include <memory>
19 
20 class KCompTreeNode;
21 class KCompletionPrivate;
22 class KCompletionMatchesWrapper;
23 class KCompletionMatches;
24 
25 /**
26  * @class KCompletion kcompletion.h KCompletion
27  *
28  * @short A generic class for completing QStrings
29  *
30  * This class offers easy use of "auto completion", "manual completion" or
31  * "shell completion" on QString objects. A common use is completing filenames
32  * or URLs (see KUrlCompletion()).
33  * But it is not limited to URL-completion -- everything should be completable!
34  * The user should be able to complete email addresses, telephone numbers,
35  * commands, SQL queries...
36  * Every time your program knows what the user can type into an edit field, you
37  * should offer completion. With KCompletion, this is very easy, and if you are
38  * using a line edit widget (KLineEdit), it is even easier.
39  * Basically, you tell a KCompletion object what strings should be completable
40  * and, whenever completion should be invoked, you call makeCompletion().
41  * KLineEdit and (an editable) KComboBox even do this automatically for you.
42  *
43  * KCompletion offers the completed string via the signal match() and
44  * all matching strings (when the result is ambiguous) via the method
45  * allMatches().
46  *
47  * Notice: auto completion, shell completion and manual completion work
48  * slightly differently:
49  *
50  * @li auto completion always returns a complete item as match.
51  * When more than one matching item is available, it will deliver just
52  * the first one (depending on sorting order). Iterating over all matches
53  * is possible via nextMatch() and previousMatch().
54  *
55  * @li popup completion works in the same way, the only difference being that
56  * the completed items are not put into the edit widget, but into a
57  * separate popup box.
58  *
59  * @li manual completion works the same way as auto completion, except that
60  * it is not invoked automatically while the user is typing,
61  * but only when the user presses a special key. The difference
62  * of manual and auto completion is therefore only visible in UI classes.
63  * KCompletion needs to know whether to deliver partial matches
64  * (shell completion) or whole matches (auto/manual completion), therefore
65  * KCompletion::CompletionMan and KCompletion::CompletionAuto have the exact
66  * same effect in KCompletion.
67  *
68  * @li shell completion works like "tab completion" in a shell:
69  * when multiple matches are available, the longest possible string of all
70  * matches is returned (i.e. only a partial item).
71  * Iterating over all matching items (complete, not partial) is possible
72  * via nextMatch() and previousMatch().
73  *
74  * As an application programmer, you do not normally have to worry about
75  * the different completion modes; KCompletion handles
76  * that for you, according to the setting setCompletionMode().
77  * The default setting is globally configured by the user and read
78  * from completionMode().
79  *
80  * A short example:
81  * \code
82  * KCompletion completion;
83  * completion.setOrder(KCompletion::Sorted);
84  * completion.addItem("[email protected]");
85  * completion.addItem("[email protected]");
86  * completion.addItem("[email protected]");
87  * completion.addItem("[email protected]");
88  *
89  * cout << completion.makeCompletion("ca").latin1() << endl;
90  * \endcode
91  *
92  * In shell-completion mode, this will be "carp"; in auto-completion
93  * mode it will be "carp\@cs.tu-berlin.de", as that is alphabetically
94  * smaller.
95  * If setOrder was set to Insertion, "carpdjih\@sp.zrz.tu-berlin.de"
96  * would be completed in auto-completion mode, as that was inserted before
97  * "carp\@cs.tu-berlin.de".
98  *
99  * You can dynamically update the completable items by removing and adding them
100  * whenever you want.
101  * For advanced usage, you could even use multiple KCompletion objects. E.g.
102  * imagine an editor like kwrite with multiple open files. You could store
103  * items of each file in a different KCompletion object, so that you know (and
104  * tell the user) where a completion comes from.
105  *
106  * @note KCompletion does not work with strings that contain 0x0 characters
107  * (unicode null), as this is used internally as a delimiter.
108  *
109  * You may inherit from KCompletion and override makeCompletion() in
110  * special cases (like reading directories or urls and then supplying the
111  * contents to KCompletion, as KUrlCompletion does), but this is usually
112  * not necessary.
113  *
114  *
115  * @author Carsten Pfeiffer <[email protected]>
116  */
117 class KCOMPLETION_EXPORT KCompletion : public QObject
118 {
119  Q_PROPERTY(CompOrder order READ order WRITE setOrder)
120  Q_PROPERTY(bool ignoreCase READ ignoreCase WRITE setIgnoreCase)
121  Q_PROPERTY(QStringList items READ items WRITE setItems)
122  Q_OBJECT
123  Q_DECLARE_PRIVATE(KCompletion)
124 
125 public:
126  /**
127  * This enum describes the completion mode used for by the KCompletion class.
128  *
129  * @since 5.0
130  */
132  /**
133  * No completion is used.
134  */
135  CompletionNone = 1,
136  /**
137  * Text is automatically filled in whenever possible.
138  */
140  /**
141  * Same as automatic, but shortest match is used for completion.
142  */
144  /**
145  * Completes text much in the same way as a typical *nix shell would.
146  */
148  /**
149  * Lists all possible matches in a popup list box to choose from.
150  */
152  /**
153  * Lists all possible matches in a popup list box to choose from, and automatically
154  * fills the result whenever possible.
155  */
157  };
158 
159  /**
160  * Constants that represent the order in which KCompletion performs
161  * completion lookups.
162  */
163  enum CompOrder {
164  Sorted, ///< Use alphabetically sorted order or custom sorter logic
165  Insertion, ///< Use order of insertion
166  Weighted, ///< Use weighted order
167  };
168  Q_ENUM(CompOrder)
169 
170  /**
171  * The sorter function signature. Deriving classes may provide
172  * custom sorting logic via the setSorterFunction method.
173  *
174  * @since 5.88
175  */
176  using SorterFunction = std::function<void(QStringList &)>;
177 
178  /**
179  * Constructor, nothing special here :)
180  */
181  KCompletion();
182 
183  /**
184  * Destructor, nothing special here, either.
185  */
186  ~KCompletion() override;
187 
188  /**
189  * Returns a list of all completion items that contain the given @p string.
190  * @param string the string to complete
191  * @return a list of items which contain @p text as a substring,
192  * i.e. not necessarily at the beginning.
193  *
194  * @see makeCompletion
195  */
196  QStringList substringCompletion(const QString &string) const;
197 
198  /**
199  * Returns the last match. Might be useful if you need to check whether
200  * a completion is different from the last one.
201  * @return the last match. QString() is returned when there is no
202  * last match.
203  */
204  virtual const QString &lastMatch() const;
205 
206  /**
207  * Returns a list of all items inserted into KCompletion. This is useful
208  * if you need to save the state of a KCompletion object and restore it
209  * later.
210  *
211  * @note When order() == Weighted, then every item in the
212  * stringlist has its weight appended, delimited by a colon. E.g. an item
213  * "www.kde.org" might look like "www.kde.org:4", where 4 is the weight.
214  * This is necessary so that you can save the items along with its
215  * weighting on disk and load them back with setItems(), restoring its
216  * weight as well. If you really don't want the appended weightings, call
217  * setOrder( KCompletion::Insertion ) before calling items().
218  *
219  * @return a list of all items
220  * @see setItems
221  */
222  QStringList items() const;
223 
224  /**
225  * Returns true if the completion object contains no entries.
226  */
227  bool isEmpty() const;
228 
229  /**
230  * Sets the completion mode.
231  * @param mode the completion mode
232  * @see CompletionMode
233  */
234  virtual void setCompletionMode(CompletionMode mode);
235 
236  /**
237  * Returns the current completion mode.
238  *
239  * @return the current completion mode, default is CompletionPopup
240  * @see setCompletionMode
241  * @see CompletionMode
242  */
243  CompletionMode completionMode() const;
244 
245  /**
246  * KCompletion offers three different ways in which it offers its items:
247  * @li in the order of insertion
248  * @li sorted alphabetically
249  * @li weighted
250  *
251  * Choosing weighted makes KCompletion perform an implicit weighting based
252  * on how often an item is inserted. Imagine a web browser with a location
253  * bar, where the user enters URLs. The more often a URL is entered, the
254  * higher priority it gets.
255  *
256  * @note Setting the order to sorted only affects new inserted items,
257  * already existing items will stay in the current order. So you probably
258  * want to call setOrder(Sorted) before inserting items if you want
259  * everything sorted.
260  *
261  * Default is insertion order.
262  * @param order the new order
263  * @see order
264  */
265  virtual void setOrder(CompOrder order);
266 
267  /**
268  * Returns the completion order.
269  * @return the current completion order.
270  * @see setOrder
271  */
272  CompOrder order() const;
273 
274  /**
275  * Setting this to true makes KCompletion behave case insensitively.
276  * E.g. makeCompletion("CA"); might return "carp\@cs.tu-berlin.de".
277  * Default is false (case sensitive).
278  * @param ignoreCase true to ignore the case
279  * @see ignoreCase
280  */
281  virtual void setIgnoreCase(bool ignoreCase);
282 
283  /**
284  * Returns whether KCompletion acts case insensitively or not.
285  * Default is false (case sensitive).
286  * @return true if the case will be ignored
287  * @see setIgnoreCase
288  */
289  bool ignoreCase() const;
290 
291  /**
292  * Informs the caller if they should display the auto-suggestion for the last completion operation performed.
293  * Applies for CompletionPopupAuto and CompletionAuto modes.
294  * Defaults to true, but deriving classes may set it to false in special cases via "setShouldAutoSuggest".
295  * @return true if auto-suggestion should be displayed for the last completion operation performed.
296  * @since 5.87
297  */
298  bool shouldAutoSuggest() const;
299 
300  /**
301  * Returns a list of all items matching the last completed string.
302  * It might take some time if you have a @em lot of items.
303  * @return a list of all matches for the last completed string.
304  * @see substringCompletion
305  */
306  QStringList allMatches();
307 
308  /**
309  * Returns a list of all items matching @p string.
310  * @param string the string to match
311  * @return the list of all matches
312  */
313  QStringList allMatches(const QString &string);
314 
315  /**
316  * Returns a list of all items matching the last completed string.
317  * It might take some time if you have a @em lot of items.
318  * The matches are returned as KCompletionMatches, which also
319  * keeps the weight of the matches, allowing
320  * you to modify some matches or merge them with matches
321  * from another call to allWeightedMatches(), and sort the matches
322  * after that in order to have the matches ordered correctly.
323  *
324  * @return a list of all completion matches
325  * @see substringCompletion
326  */
327  KCompletionMatches allWeightedMatches();
328 
329  /**
330  * Returns a list of all items matching @p string.
331  * @param string the string to match
332  * @return a list of all matches
333  */
334  KCompletionMatches allWeightedMatches(const QString &string);
335 
336  /**
337  * Enables/disables emitting a sound when
338  * @li makeCompletion() can't find a match
339  * @li there is a partial completion (= multiple matches in
340  * Shell-completion mode)
341  * @li nextMatch() or previousMatch() hit the last possible
342  * match and the list is rotated
343  *
344  * KNotifyClient() is used to emit the sounds.
345  *
346  * @param enable true to enable sounds
347  * @see soundsEnabled
348  */
349  virtual void setSoundsEnabled(bool enable);
350 
351  /**
352  * Tells you whether KCompletion will emit sounds on certain occasions.
353  * Default is enabled.
354  * @return true if sounds are enabled
355  * @see setSoundsEnabled
356  */
357  bool soundsEnabled() const;
358 
359  /**
360  * Returns true when more than one match is found.
361  * @return true if there is more than one match
362  * @see multipleMatches
363  */
364  bool hasMultipleMatches() const;
365 
366 public Q_SLOTS:
367  /**
368  * Attempts to find an item in the list of available completions
369  * that begins with @p string. Will either return the first matching item
370  * (if there is more than one match) or QString(), if no match is
371  * found.
372  *
373  * In the latter case, a sound will be emitted, depending on
374  * soundsEnabled().
375  * If a match is found, it will be emitted via the signal
376  * match().
377  *
378  * If this is called twice or more with the same string while no
379  * items were added or removed in the meantime, all available completions
380  * will be emitted via the signal matches().
381  * This happens only in shell-completion mode.
382  *
383  * @param string the string to complete
384  * @return the matching item, or QString() if there is no matching
385  * item.
386  * @see substringCompletion
387  */
388  virtual QString makeCompletion(const QString &string);
389 
390  /**
391  * Returns the next item from the list of matching items.
392  * When reaching the beginning, the list is rotated so it will return the
393  * last match and a sound is emitted (depending on soundsEnabled()).
394  * @return the next item from the list of matching items.
395  * When there is no match, QString() is returned and
396  * a sound is emitted.
397  */
398  QString previousMatch();
399 
400  /**
401  * Returns the next item from the list of matching items.
402  * When reaching the last item, the list is rotated, so it will return
403  * the first match and a sound is emitted (depending on
404  * soundsEnabled()).
405  * @return the next item from the list of matching items. When there is no
406  * match, QString() is returned and a sound is emitted.
407  */
408  QString nextMatch();
409 
410 #if KCOMPLETION_ENABLE_DEPRECATED_SINCE(5, 0)
411  /**
412  * Attempts to complete "string" and emits the completion via match().
413  * Same as makeCompletion(), but in this case as a slot.
414  * @param string the string to complete
415  * @see makeCompletion
416  * @deprecated since 5.0, use makeCompletion() instead
417  */
418  KCOMPLETION_DEPRECATED_VERSION(5, 0, "Use KCompletion::makeCompletion(const QString &)")
419  void slotMakeCompletion(const QString &string) // inline (redirect)
420  {
421  (void)makeCompletion(string);
422  }
423 #endif
424 
425 #if KCOMPLETION_ENABLE_DEPRECATED_SINCE(5, 0)
426  /**
427  * Searches the previous matching item and emits it via match().
428  * Same as previousMatch(), but in this case as a slot.
429  * @see previousMatch
430  * @deprecated since 5.0, use previousMatch() instead
431  */
432  KCOMPLETION_DEPRECATED_VERSION(5, 0, "Use KCompletion::previousMatch()")
433  void slotPreviousMatch() // inline (redirect)
434  {
435  (void)previousMatch();
436  }
437 #endif
438 
439 #if KCOMPLETION_ENABLE_DEPRECATED_SINCE(5, 0)
440  /**
441  * Searches the next matching item and emits it via match().
442  * Same as nextMatch(), but in this case as a slot.
443  * @see nextMatch
444  * @deprecated since 5.0, use nextMatch() instead
445  */
446  KCOMPLETION_DEPRECATED_VERSION(5, 0, "Use KCompletion::nextMatch()")
447  void slotNextMatch() // inline (redirect)
448  {
449  (void)nextMatch();
450  }
451 #endif
452 
453  /**
454  * Inserts @p items into the list of possible completions.
455  * It does the same as setItems(), but without calling clear() before.
456  * @param items the items to insert
457  */
458  void insertItems(const QStringList &items);
459 
460  /**
461  * Sets the list of items available for completion. Removes all previous
462  * items.
463  *
464  * @note When order() == Weighted, then the weighting is looked up for
465  * every item in the stringlist. Every item should have ":number" appended,
466  * where number is an unsigned integer, specifying the weighting.
467  * If you don't like this, call
468  * setOrder(KCompletion::Insertion)
469  * before calling setItems().
470  *
471  * @param itemList the list of items that are available for completion
472  * @see items
473  */
474  virtual void setItems(const QStringList &itemList);
475 
476  /**
477  * Adds an item to the list of available completions.
478  * Resets the current item state (previousMatch() and nextMatch()
479  * won't work the next time they are called).
480  * @param item the item to add
481  */
482  void addItem(const QString &item);
483 
484  /**
485  * Adds an item to the list of available completions.
486  * Resets the current item state (previousMatch() and nextMatch()
487  * won't work the next time they are called).
488  *
489  * Sets the weight of the item to @p weight or adds it to the current
490  * weight if the item is already available. The weight has to be greater
491  * than 1 to take effect (default weight is 1).
492  * @param item the item to add
493  * @param weight the weight of the item, default is 1
494  */
495  void addItem(const QString &item, uint weight);
496 
497  /**
498  * Removes an item from the list of available completions.
499  * Resets the current item state (previousMatch() and nextMatch()
500  * won't work the next time they are called).
501  * @param item the item to remove
502  */
503  void removeItem(const QString &item);
504 
505  /**
506  * Removes all inserted items.
507  */
508  virtual void clear();
509 
510 Q_SIGNALS:
511  /**
512  * This signal is emitted when a match is found.
513  *
514  * In particular, makeCompletion(), previousMatch() and nextMatch()
515  * all emit this signal; makeCompletion() will only emit it when a
516  * match is found, but the other methods will always emit it (and so
517  * may emit it with an empty string).
518  *
519  * @param item the matching item, or QString() if there were no more
520  * matching items.
521  */
522  void match(const QString &item);
523 
524  /**
525  * This signal is emitted by makeCompletion() in shell-completion mode
526  * when the same string is passed to makeCompletion() multiple times in
527  * a row.
528  * @param matchlist the list of all matching items
529  */
530  void matches(const QStringList &matchlist);
531 
532  /**
533  * This signal is emitted when calling makeCompletion() and more than
534  * one matching item is found.
535  * @see hasMultipleMatches
536  */
537  void multipleMatches();
538 
539 protected:
540  /**
541  * This method is called after a completion is found and before the
542  * matching string is emitted. You can override this method to modify the
543  * string that will be emitted.
544  * This is necessary e.g. in KUrlCompletion(), where files with spaces
545  * in their names are shown escaped ("filename\ with\ spaces"), but stored
546  * unescaped inside KCompletion.
547  * Never delete that pointer!
548  *
549  * Default implementation does nothing.
550  * @param match the match to process
551  * @see postProcessMatches
552  */
553  virtual void postProcessMatch(QString *match) const;
554 
555  /**
556  * This method is called before a list of all available completions is
557  * emitted via matches(). You can override this method to modify the
558  * found items before match() or matches() are emitted.
559  * Never delete that pointer!
560  *
561  * Default implementation does nothing.
562  * @param matchList the matches to process
563  * @see postProcessMatch
564  */
565  virtual void postProcessMatches(QStringList *matchList) const;
566 
567  /**
568  * This method is called before a list of all available completions is
569  * emitted via #matches(). You can override this method to modify the
570  * found items before #match() or #matches() are emitted.
571  * Never delete that pointer!
572  *
573  * Default implementation does nothing.
574  * @param matches the matches to process
575  * @see postProcessMatch
576  */
577  virtual void postProcessMatches(KCompletionMatches *matches) const;
578 
579  /**
580  * Deriving classes may set this property and control whether the auto-suggestion should be displayed
581  * for the last completion operation performed.
582  *
583  * Applies for CompletionPopupAuto and CompletionAuto modes.
584  * @since 5.87
585  */
586  void setShouldAutoSuggest(bool shouldAutosuggest);
587 
588  /**
589  * Sets a custom function to be used to sort the matches.
590  * Can be set to nullptr to use the default sorting logic.
591  *
592  * Applies for CompOrder::Sorted mode.
593  * @since 5.88
594  */
595  void setSorterFunction(SorterFunction sortFunc);
596 
597 private:
599  std::unique_ptr<KCompletionPrivate> const d_ptr;
600 };
601 
602 #endif // KCOMPLETION_H
Q_PROPERTY(...)
@ CompletionAuto
Text is automatically filled in whenever possible.
Definition: kcompletion.h:139
@ CompletionPopup
Lists all possible matches in a popup list box to choose from.
Definition: kcompletion.h:151
Q_ENUM(...)
A generic class for completing QStrings.
Definition: kcompletion.h:117
@ CompletionMan
Same as automatic, but shortest match is used for completion.
Definition: kcompletion.h:143
@ Weighted
Use weighted order.
Definition: kcompletion.h:166
CompletionMode
This enum describes the completion mode used for by the KCompletion class.
Definition: kcompletion.h:131
@ Insertion
Use order of insertion.
Definition: kcompletion.h:165
CompOrder
Constants that represent the order in which KCompletion performs completion lookups.
Definition: kcompletion.h:163
List for keeping matches returned from KCompletion.
@ CompletionShell
Completes text much in the same way as a typical *nix shell would.
Definition: kcompletion.h:147
@ CompletionPopupAuto
Lists all possible matches in a popup list box to choose from, and automatically fills the result whe...
Definition: kcompletion.h:156
Q_SIGNALSQ_SIGNALS
std::function< void(QStringList &)> SorterFunction
The sorter function signature.
Definition: kcompletion.h:176
Q_DISABLE_COPY(Class)
@ Sorted
Use alphabetically sorted order or custom sorter logic.
Definition: kcompletion.h:164
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Dec 5 2023 03:57:53 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.