1/* This file is part of the KDE libraries
2 Copyright (C) 1999,2000 Carsten Pfeiffer <pfeiffer@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 as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KCOMPLETION_H
21#define KCOMPLETION_H
22
23#include <kdeui_export.h>
24#include <kglobalsettings.h>
25#include <ksortablelist.h>
26#include <kshortcut.h>
27
28#include <QtCore/QMap>
29#include <QtCore/QObject>
30#include <QtCore/QString>
31#include <QtCore/QStringList>
32#include <QtCore/QPointer>
33
34class KCompTreeNode;
35class KCompletionPrivate;
36class KCompletionBasePrivate;
37class KCompletionMatchesWrapper;
38class KCompletionMatches;
39
40/**
41 * @short A generic class for completing QStrings
42 *
43 * This class offers easy use of "auto-completion", "manual-completion" or
44 * "shell completion" on QString objects. A common use is completing filenames
45 * or URLs (see KUrlCompletion()).
46 * But it is not limited to URL-completion -- everything should be completable!
47 * The user should be able to complete email-addresses, telephone-numbers,
48 * commands, SQL queries, ...
49 * Every time your program knows what the user can type into an edit-field, you
50 * should offer completion. With KCompletion, this is very easy, and if you are
51 * using a line edit widget ( KLineEdit), it is even more easy.
52 * Basically, you tell a KCompletion object what strings should be completable
53 * and whenever completion should be invoked, you call makeCompletion().
54 * KLineEdit and (an editable) KComboBox even do this automatically for you.
55 *
56 * KCompletion offers the completed string via the signal match() and
57 * all matching strings (when the result is ambiguous) via the method
58 * allMatches().
59 *
60 * Notice: auto-completion, shell completion and manual completion work
61 * slightly differently:
62 *
63 * @li auto-completion always returns a complete item as match.
64 * When more than one matching items are available, it will deliver just
65 * the first (depending on sorting order) item. Iterating over all matches
66 * is possible via nextMatch() and previousMatch().
67 *
68 * @li popup-completion works in the same way, the only difference being that
69 * the completed items are not put into the edit-widget, but into a
70 * separate popup-box.
71 *
72 * @li manual completion works the same way as auto-completion, the
73 * subtle difference is, that it isn't invoked automatically while the user
74 * is typing, but only when the user presses a special key. The difference
75 * of manual and auto-completion is therefore only visible in UI classes,
76 * KCompletion needs to know whether to deliver partial matches
77 * (shell completion) or whole matches (auto/manual completion), therefore
78 * KGlobalSettings::CompletionMan and
79 * KGlobalSettings::CompletionAuto have the exact same effect in
80 * KCompletion.
81 *
82 * @li shell completion works like how shells complete filenames:
83 * when multiple matches are available, the longest possible string of all
84 * matches is returned (i.e. only a partial item).
85 * Iterating over all matching items (complete, not partial) is possible
86 * via nextMatch() and previousMatch().
87 *
88 * You don't have to worry much about that though, KCompletion handles
89 * that for you, according to the setting setCompletionMode().
90 * The default setting is globally configured by the user and read
91 * from KGlobalSettings::completionMode().
92 *
93 * A short example:
94 * \code
95 * KCompletion completion;
96 * completion.setOrder( KCompletion::Sorted );
97 * completion.addItem( "pfeiffer@kde.org" );
98 * completion.addItem( "coolo@kde.org" );
99 * completion.addItem( "carpdjih@sp.zrz.tu-berlin.de" );
100 * completion.addItem( "carp@cs.tu-berlin.de" );
101 *
102 * cout << completion.makeCompletion( "ca" ).latin1() << endl;
103 * \endcode
104 *
105 * In shell-completion-mode, this will be "carp"; in auto-completion-
106 * mode it will be "carp\@cs.tu-berlin.de", as that is alphabetically
107 * smaller.
108 * If setOrder was set to Insertion, "carpdjih\@sp.zrz.tu-berlin.de"
109 * would be completed in auto-completion-mode, as that was inserted before
110 * "carp\@cs.tu-berlin.de".
111 *
112 * You can dynamically update the completable items by removing and adding them
113 * whenever you want.
114 * For advanced usage, you could even use multiple KCompletion objects. E.g.
115 * imagine an editor like kwrite with multiple open files. You could store
116 * items of each file in a different KCompletion object, so that you know (and
117 * tell the user) where a completion comes from.
118 *
119 * Note: KCompletion does not work with strings that contain 0x0 characters
120 * (unicode nul), as this is used internally as a delimiter.
121 *
122 * You may inherit from KCompletion and override makeCompletion() in
123 * special cases (like reading directories/urls and then supplying the
124 * contents to KCompletion, as KUrlCompletion does), but generally, this is
125 * not necessary.
126 *
127 *
128 * @author Carsten Pfeiffer <pfeiffer@kde.org>
129 */
130class KDEUI_EXPORT KCompletion : public QObject
131{
132 Q_ENUMS( CompOrder )
133 Q_PROPERTY( CompOrder order READ order WRITE setOrder )
134 Q_PROPERTY( bool ignoreCase READ ignoreCase WRITE setIgnoreCase )
135 Q_PROPERTY( QStringList items READ items WRITE setItems )
136 Q_OBJECT
137
138public:
139 /**
140 * Constants that represent the order in which KCompletion performs
141 * completion-lookups.
142 */
143 enum CompOrder { Sorted, ///< Use alphabetically sorted order
144 Insertion, ///< Use order of insertion
145 Weighted ///< Use weighted order
146 };
147
148 /**
149 * Constructor, nothing special here :)
150 */
151 KCompletion();
152
153 /**
154 * Destructor, nothing special here, either.
155 */
156 virtual ~KCompletion();
157
158 /**
159 * Attempts to find an item in the list of available completions,
160 * that begins with @p string. Will either return the first matching item
161 * (if there is more than one match) or QString(), if no match was
162 * found.
163 *
164 * In the latter case, a sound will be issued, depending on
165 * soundsEnabled().
166 * If a match was found, it will also be emitted via the signal
167 * match().
168 *
169 * If this is called twice or more often with the same string while no
170 * items were added or removed in the meantime, all available completions
171 * will be emitted via the signal #matches().
172 * This happens only in shell-completion-mode.
173 *
174 * @param string the string to complete
175 * @return the matching item, or QString() if there is no matching
176 * item.
177 * @see slotMakeCompletion
178 * @see substringCompletion
179 */
180 virtual QString makeCompletion( const QString& string );
181
182 /**
183 * Returns a list of all completion items that contain the given @p string.
184 * @param string the string to complete
185 * @return a list of items which all contain @p text as a substring,
186 * i.e. not necessarily at the beginning.
187 *
188 * @see makeCompletion
189 */
190 QStringList substringCompletion( const QString& string ) const;
191
192 /**
193 * Returns the next item from the matching-items-list.
194 * When reaching the beginning, the list is rotated so it will return the
195 * last match and a sound is issued (depending on soundsEnabled()).
196 * @return the next item from the matching-items-list.
197 * When there is no match, QString() is returned and
198 * a sound is be issued.
199 * @see slotPreviousMatch
200 */
201 QString previousMatch();
202
203 /**
204 * Returns the next item from the matching-items-list.
205 * When reaching the last item, the list is rotated, so it will return
206 * the first match and a sound is issued (depending on
207 * soundsEnabled()).
208 * @return the next item from the matching-items-list. When there is no
209 * match, QString() is returned and a sound is issued
210 * @see slotNextMatch
211 */
212 QString nextMatch();
213
214 /**
215 * Returns the last match. Might be useful if you need to check whether
216 * a completion is different from the last one.
217 * @return the last match. QString() is returned when there is no
218 * last match.
219 */
220 virtual const QString& lastMatch() const;
221
222 /**
223 * Returns a list of all items inserted into KCompletion. This is useful
224 * if you need to save the state of a KCompletion object and restore it
225 * later.
226 *
227 * Important note: when order() == Weighted, then every item in the
228 * stringlist has its weight appended, delimited by a colon. E.g. an item
229 * "www.kde.org" might look like "www.kde.org:4", where 4 is the weight.
230 *
231 * This is necessary so that you can save the items along with its
232 * weighting on disk and load them back with setItems(), restoring its
233 * weight as well. If you really don't want the appended weightings, call
234 * setOrder( KCompletion::Insertion )
235 * before calling items().
236 *
237 * @return a list of all items
238 * @see setItems
239 */
240 QStringList items() const;
241
242 /**
243 * Returns true when the completion object contains no entries.
244 */
245 bool isEmpty() const;
246
247 /**
248 * Sets the completion mode to Auto/Manual, Shell or None.
249 * If you don't set the mode explicitly, the global default value
250 * KGlobalSettings::completionMode() is used.
251 * KGlobalSettings::CompletionNone disables completion.
252 * @param mode the completion mode
253 * @see completionMode
254 * @see KGlobalSettings::completionMode
255 */
256 virtual void setCompletionMode( KGlobalSettings::Completion mode );
257
258 /**
259 * Return the current completion mode.
260 * May be different from KGlobalSettings::completionMode(), if you
261 * explicitly called setCompletionMode().
262 * @return the current completion mode
263 * @see setCompletionMode
264 */
265 KGlobalSettings::Completion completionMode() const;
266
267 /**
268 * KCompletion offers three different ways in which it offers its items:
269 * @li in the order of insertion
270 * @li sorted alphabetically
271 * @li weighted
272 *
273 * Choosing weighted makes KCompletion perform an implicit weighting based
274 * on how often an item is inserted. Imagine a web browser with a location
275 * bar, where the user enters URLs. The more often a URL is entered, the
276 * higher priority it gets.
277 *
278 * Note: Setting the order to sorted only affects new inserted items,
279 * already existing items will stay in the current order. So you probably
280 * want to call setOrder( Sorted ) before inserting items, when you want
281 * everything sorted.
282 *
283 * Default is insertion order.
284 * @param order the new order
285 * @see order
286 */
287 virtual void setOrder( CompOrder order );
288
289 /**
290 * Returns the completion order.
291 * @return the current completion order.
292 * @see setOrder
293 */
294 CompOrder order() const;
295
296 /**
297 * Setting this to true makes KCompletion behave case insensitively.
298 * E.g. makeCompletion( "CA" ); might return "carp\@cs.tu-berlin.de".
299 * Default is false (case sensitive).
300 * @param ignoreCase true to ignore the case
301 * @see ignoreCase
302 */
303 virtual void setIgnoreCase( bool ignoreCase );
304
305 /**
306 * Return whether KCompletion acts case insensitively or not.
307 * Default is false (case sensitive).
308 * @return true if the case will be ignored
309 * @see setIgnoreCase
310 */
311 bool ignoreCase() const;
312
313 /**
314 * Returns a list of all items matching the last completed string.
315 * Might take some time, when you have LOTS of items.
316 * @return a list of all matches for the last completed string.
317 * @see substringCompletion
318 */
319 QStringList allMatches();
320
321 /**
322 * Returns a list of all items matching @p string.
323 * @param string the string to match
324 * @return the list of all matches
325 */
326 QStringList allMatches( const QString& string );
327
328 /**
329 * Returns a list of all items matching the last completed string.
330 * Might take some time, when you have LOTS of items.
331 * The matches are returned as KCompletionMatches, which also
332 * keeps the weight of the matches, allowing
333 * you to modify some matches or merge them with matches
334 * from another call to allWeightedMatches(), and sort the matches
335 * after that in order to have the matches ordered correctly.
336 *
337 * @return a list of all completion matches
338 * @see substringCompletion
339 */
340 KCompletionMatches allWeightedMatches();
341
342 /**
343 * Returns a list of all items matching @p string.
344 * @param string the string to match
345 * @return a list of all matches
346 */
347 KCompletionMatches allWeightedMatches( const QString& string );
348
349 /**
350 * Enables/disables playing a sound when
351 * @li makeCompletion() can't find a match
352 * @li there is a partial completion (= multiple matches in
353 * Shell-completion mode)
354 * @li nextMatch() or previousMatch() hit the last possible
355 * match -> rotation
356 *
357 * For playing the sounds, KNotifyClient() is used.
358 *
359 * @param enable true to enable sounds
360 * @see soundsEnabled
361 */
362 virtual void setSoundsEnabled( bool enable );
363
364 /**
365 * Tells you whether KCompletion will play sounds on certain occasions.
366 * Default is enabled.
367 * @return true if sounds are enabled
368 * @see setSoundsEnabled
369 */
370 bool soundsEnabled() const;
371
372 /**
373 * Returns true when more than one match is found.
374 * @return true if there are more than one match
375 * @see multipleMatches
376 */
377 bool hasMultipleMatches() const;
378
379public Q_SLOTS:
380 /**
381 * Attempts to complete "string" and emits the completion via match().
382 * Same as makeCompletion() (just as a slot).
383 * @param string the string to complete
384 * @see makeCompletion
385 */
386 void slotMakeCompletion( const QString& string ) { //inline (redirect)
387 (void) makeCompletion( string );
388 }
389
390 /**
391 * Searches the previous matching item and emits it via match().
392 * Same as previousMatch() (just as a slot).
393 * @see previousMatch
394 */
395 void slotPreviousMatch() { //inline (redirect)
396 (void) previousMatch();
397 }
398
399 /**
400 * Searches the next matching item and emits it via match().
401 * Same as nextMatch() (just as a slot).
402 * @see nextMatch
403 */
404 void slotNextMatch() { //inline (redirect)
405 (void) nextMatch();
406 }
407
408 // FIXME ###: KDE4: unify the nomenclature. We have insertItems, addItem,
409 // setItems...
410 /**
411 * Inserts @p items into the list of possible completions.
412 * Does the same as setItems(), but does not call clear() before.
413 * @param items the items to insert
414 */
415 void insertItems( const QStringList& items );
416
417 /**
418 * Sets the list of items available for completion. Removes all previous
419 * items.
420 *
421 * Notice: when order() == Weighted, then the weighting is looked up for
422 * every item in the stringlist. Every item should have ":number" appended,
423 * where number is an unsigned integer, specifying the weighting.
424 *
425 * If you don't like this, call
426 * setOrder( KCompletion::Insertion )
427 * before calling setItems().
428 *
429 * @param list the list of items that are available for completion
430 * @see items
431 */
432 virtual void setItems( const QStringList& list);
433
434 /**
435 * Adds an item to the list of available completions.
436 * Resets the current item-state ( previousMatch() and nextMatch()
437 * won't work anymore).
438 * @param item the item to add
439 */
440 void addItem( const QString& item);
441
442 /**
443 * Adds an item to the list of available completions.
444 * Resets the current item-state ( previousMatch() and nextMatch()
445 * won't work anymore).
446 *
447 * Sets the weighting of the item to @p weight or adds it to the current
448 * weighting if the item is already available. The weight has to be greater
449 * than 1 to take effect (default weight is 1).
450 * @param item the item to add
451 * @param weight the weight of the item, default is 1
452 */
453 void addItem( const QString& item, uint weight );
454
455 /**
456 * Removes an item from the list of available completions.
457 * Resets the current item-state ( previousMatch() and nextMatch()
458 * won't work anymore).
459 * @param item the item to remove
460 */
461 void removeItem( const QString& item);
462
463 /**
464 * Removes all inserted items.
465 */
466 virtual void clear();
467
468
469Q_SIGNALS:
470 /**
471 * The matching item. Will be emitted by makeCompletion(),
472 * previousMatch() or nextMatch(). May be QString() if there
473 * is no matching item.
474 * @param item the match, or QString() if there is none
475 */
476 void match( const QString& item);
477
478 /**
479 * All matching items. Will be emitted by makeCompletion() in shell-
480 * completion-mode, when the same string is passed to makeCompletion twice
481 * or more often.
482 * @param matchlist the list of matches
483 */
484 void matches( const QStringList& matchlist);
485
486 /**
487 * This signal is emitted, when calling makeCompletion() and more than
488 * one matching item is found.
489 * @see hasMultipleMatches
490 */
491 void multipleMatches();
492
493protected:
494 /**
495 * This method is called after a completion is found and before the
496 * matching string is emitted. You can override this method to modify the
497 * string that will be emitted.
498 * This is necessary e.g. in KUrlCompletion(), where files with spaces
499 * in their names are shown escaped ("filename\ with\ spaces"), but stored
500 * unescaped inside KCompletion.
501 * Never delete that pointer!
502 *
503 * Default implementation does nothing.
504 * @param pMatch the match to process
505 * @see postProcessMatches
506 */
507 virtual void postProcessMatch( QString *pMatch ) const;
508
509 /**
510 * This method is called before a list of all available completions is
511 * emitted via #matches. You can override this method to modify the
512 * found items before match() or #matches are emitted.
513 * Never delete that pointer!
514 *
515 * Default implementation does nothing.
516 * @param pMatches the matches to process
517 * @see postProcessMatch
518 */
519 virtual void postProcessMatches( QStringList * pMatches ) const;
520
521 /**
522 * This method is called before a list of all available completions is
523 * emitted via #matches. You can override this method to modify the
524 * found items before #match() or #matches() are emitted.
525 * Never delete that pointer!
526 *
527 * Default implementation does nothing.
528 * @param pMatches the matches to process
529 * @see postProcessMatch
530 */
531 virtual void postProcessMatches( KCompletionMatches * pMatches ) const;
532
533private:
534 void addWeightedItem( const QString& );
535 QString findCompletion( const QString& string );
536 void findAllCompletions( const QString&,
537 KCompletionMatchesWrapper *matches,
538 bool& hasMultipleMatches ) const;
539
540 void extractStringsFromNode( const KCompTreeNode *,
541 const QString& beginning,
542 KCompletionMatchesWrapper *matches,
543 bool addWeight = false ) const;
544 void extractStringsFromNodeCI( const KCompTreeNode *,
545 const QString& beginning,
546 const QString& restString,
547 KCompletionMatchesWrapper *matches) const;
548
549 enum BeepMode { NoMatch, PartialMatch, Rotation };
550 void doBeep( BeepMode ) const;
551
552private:
553 Q_DISABLE_COPY( KCompletion )
554 KCompletionPrivate* const d;
555};
556
557// some more helper stuff
558typedef KSortableList<QString> KCompletionMatchesList;
559class KCompletionMatchesPrivate;
560
561/**
562 * This structure is returned by KCompletion::allWeightedMatches .
563 * It also keeps the weight of the matches, allowing
564 * you to modify some matches or merge them with matches
565 * from another call to allWeightedMatches(), and sort the matches
566 * after that in order to have the matches ordered correctly
567 *
568 * Example (a simplified example of what Konqueror's completion does):
569 * \code
570 * KCompletionMatches matches = completion->allWeightedMatches( location );
571 * if( !location.startsWith( "www." ))
572 matches += completion->allWeightedmatches( "www." + location" );
573 * matches.removeDuplicates();
574 * QStringList list = matches.list();
575 * \endcode
576 *
577 * @short List for keeping matches returned from KCompletion
578 */
579class KDEUI_EXPORT KCompletionMatches : public KCompletionMatchesList
580{
581public:
582 /**
583 * Default constructor.
584 * @param sort if false, the matches won't be sorted before the conversion,
585 * use only if you're sure the sorting is not needed
586 */
587 KCompletionMatches( bool sort );
588
589 /**
590 * copy constructor.
591 */
592 KCompletionMatches( const KCompletionMatches& );
593
594 /**
595 * assignment operator.
596 */
597 KCompletionMatches &operator=( const KCompletionMatches& );
598
599 /**
600 * @internal
601 */
602 KCompletionMatches( const KCompletionMatchesWrapper& matches );
603
604 /**
605 * default destructor.
606 */
607 ~KCompletionMatches();
608 /**
609 * Removes duplicate matches. Needed only when you merged several matches
610 * results and there's a possibility of duplicates.
611 */
612 void removeDuplicates();
613 /**
614 * Returns the matches as a QStringList.
615 * @param sort if false, the matches won't be sorted before the conversion,
616 * use only if you're sure the sorting is not needed
617 * @return the list of matches
618 */
619 QStringList list( bool sort = true ) const;
620 /**
621 * If sorting() returns false, the matches aren't sorted by their weight,
622 * even if true is passed to list().
623 * @return true if the matches won't be sorted
624 */
625 bool sorting() const;
626
627private:
628 KCompletionMatchesPrivate * const d;
629};
630
631/**
632 * An abstract base class for adding a completion feature
633 * into widgets.
634 *
635 * This is a convenience class that provides the basic functions
636 * needed to add text completion support into widgets. All that
637 * is required is an implementation for the pure virtual function
638 * setCompletedText. Refer to KLineEdit or KComboBox
639 * to see how easily such support can be added using this as a base
640 * class.
641 *
642 * @short An abstract class for adding text completion support to widgets.
643 * @author Dawit Alemayehu <adawit@kde.org>
644 */
645class KDEUI_EXPORT KCompletionBase
646{
647public:
648 /**
649 * Constants that represent the items whose short-cut
650 * key-binding is programmable. The default key-bindings
651 * for these items are defined in KStandardShortcut.
652 */
653 enum KeyBindingType {
654 /**
655 * Text completion (by default Ctrl-E).
656 */
657 TextCompletion,
658 /**
659 * Switch to previous completion (by default Ctrl-Up).
660 */
661 PrevCompletionMatch,
662 /**
663 * Switch to next completion (by default Ctrl-Down).
664 */
665 NextCompletionMatch,
666 /**
667 * Substring completion (by default Ctrl-T).
668 */
669 SubstringCompletion
670 };
671
672
673 // Map for the key binding types mentioned above.
674 typedef QMap<KeyBindingType, KShortcut> KeyBindingMap;
675
676 /**
677 * Default constructor.
678 */
679 KCompletionBase();
680
681 /**
682 * Destructor.
683 */
684 virtual ~KCompletionBase();
685
686 /**
687 * Returns a pointer to the current completion object.
688 *
689 * If the completion object does not exist, it is automatically created and
690 * by default handles all the completion signals internally unless @p hsig
691 * is set to false. It is also automatically destroyed when the destructor
692 * is called. You can change this default behavior using the
693 * @ref setAutoDeleteCompletionObject and @ref setHandleSignals member
694 * functions.
695 *
696 * See also @ref compObj.
697 *
698 * @param hsig if true, handles completion signals internally.
699 * @return a pointer the completion object.
700 */
701 KCompletion* completionObject( bool hsig = true );
702
703 /**
704 * Sets up the completion object to be used.
705 *
706 * This method assigns the completion object and sets it up to automatically
707 * handle the completion and rotation signals internally. You should use
708 * this function if you want to share one completion object among your
709 * widgets or need to use a customized completion object.
710 *
711 * The object assigned through this method is not deleted when this object's
712 * destructor is invoked unless you explicitly call @ref setAutoDeleteCompletionObject
713 * after calling this method. Be sure to set the bool argument to false, if
714 * you want to handle the completion signals yourself.
715 *
716 * @param compObj a KCompletion() or a derived child object.
717 * @param hsig if true, handles completion signals internally.
718 */
719 virtual void setCompletionObject( KCompletion* compObj, bool hsig = true );
720
721 /**
722 * Enables this object to handle completion and rotation
723 * events internally.
724 *
725 * This function simply assigns a boolean value that
726 * indicates whether it should handle rotation and
727 * completion events or not. Note that this does not
728 * stop the object from emitting signals when these
729 * events occur.
730 *
731 * @param handle if true, handle completion & rotation internally.
732 */
733 virtual void setHandleSignals( bool handle );
734
735 /**
736 * Returns true if the completion object is deleted
737 * upon this widget's destruction.
738 *
739 * See setCompletionObject() and enableCompletion()
740 * for details.
741 *
742 * @return true if the completion object will be deleted
743 * automatically
744 */
745 bool isCompletionObjectAutoDeleted() const;
746
747 /**
748 * Sets the completion object when this widget's destructor
749 * is called.
750 *
751 * If the argument is set to true, the completion object
752 * is deleted when this widget's destructor is called.
753 *
754 * @param autoDelete if true, delete completion object on destruction.
755 */
756 void setAutoDeleteCompletionObject( bool autoDelete );
757
758 /**
759 * Sets the widget's ability to emit text completion and
760 * rotation signals.
761 *
762 * Invoking this function with @p enable set to @p false will
763 * cause the completion & rotation signals not to be emitted.
764 * However, unlike setting the completion object to @p NULL
765 * using setCompletionObject, disabling the emition of
766 * the signals through this method does not affect the current
767 * completion object.
768 *
769 * There is no need to invoke this function by default. When a
770 * completion object is created through completionObject or
771 * setCompletionObject, these signals are set to emit
772 * automatically. Also note that disabling this signals will not
773 * necessarily interfere with the objects ability to handle these
774 * events internally. See setHandleSignals.
775 *
776 * @param enable if false, disables the emition of completion & rotation signals.
777 */
778 void setEnableSignals( bool enable );
779
780 /**
781 * Returns true if the object handles the signals.
782 *
783 * @return true if this signals are handled internally.
784 */
785 bool handleSignals() const;
786
787 /**
788 * Returns true if the object emits the signals.
789 *
790 * @return true if signals are emitted
791 */
792 bool emitSignals() const;
793
794 /**
795 * Sets the type of completion to be used.
796 *
797 * The completion modes supported are those defined in
798 * KGlobalSettings(). See below.
799 *
800 * @param mode Completion type:
801 * @li CompletionNone: Disables completion feature.
802 * @li CompletionAuto: Attempts to find a match &
803 * fills-in the remaining text.
804 * @li CompletionMan: Acts the same as the above
805 * except the action has to be
806 * manually triggered through
807 * pre-defined completion key.
808 * @li CompletionShell: Mimics the completion feature
809 * found in typical *nix shell
810 * environments.
811 * @li CompletionPopup: Shows all available completions at once,
812 * in a listbox popping up.
813 */
814 virtual void setCompletionMode( KGlobalSettings::Completion mode );
815
816 /**
817 * Returns the current completion mode.
818 *
819 * The return values are of type KGlobalSettings::Completion.
820 * See setCompletionMode() for details.
821 *
822 * @return the completion mode.
823 */
824 KGlobalSettings::Completion completionMode() const;
825
826 /**
827 * Sets the key-binding to be used for manual text
828 * completion, text rotation in a history list as
829 * well as a completion list.
830 *
831 *
832 * When the keys set by this function are pressed, a
833 * signal defined by the inheriting widget will be activated.
834 * If the default value or 0 is specified by the second
835 * parameter, then the key-binding as defined in the global
836 * setting should be used. This method returns false value
837 * for @p key is negative or the supplied key-binding conflicts
838 * with the ones set for one of the other features.
839 *
840 * NOTE: To use a modifier key (Shift, Ctrl, Alt) as part of
841 * the key-binding simply simply @p sum up the values of the
842 * modifier and the actual key. For example, to use CTRL+E as
843 * a key binding for one of the items, you would simply supply
844 * @p "Qt::CtrlButton + Qt::Key_E" as the second argument to this
845 * function.
846 *
847 * @param item the feature whose key-binding needs to be set:
848 * @li TextCompletion the manual completion key-binding.
849 * @li PrevCompletionMatch the previous match key for multiple completion.
850 * @li NextCompletionMatch the next match key for for multiple completion.
851 * @li SubstringCompletion the key for substring completion
852 * @param key key-binding used to rotate down in a list.
853 * @return true if key-binding can successfully be set.
854 * @see getKeyBinding
855 */
856 bool setKeyBinding( KeyBindingType item , const KShortcut& key );
857
858 /**
859 * Returns the key-binding used for the specified item.
860 *
861 * This methods returns the key-binding used to activate
862 * the feature feature given by @p item. If the binding
863 * contains modifier key(s), the SUM of the modifier key
864 * and the actual key code are returned.
865 *
866 * @param item the item to check
867 * @return the key-binding used for the feature given by @p item.
868 * @see setKeyBinding
869 */
870 KShortcut getKeyBinding( KeyBindingType item ) const;
871
872 /**
873 * Sets this object to use global values for key-bindings.
874 *
875 * This method changes the values of the key bindings for
876 * rotation and completion features to the default values
877 * provided in KGlobalSettings.
878 *
879 * NOTE: By default inheriting widgets should uses the
880 * global key-bindings so that there will be no need to
881 * call this method.
882 */
883 void useGlobalKeyBindings();
884
885 /**
886 * A pure virtual function that must be implemented by
887 * all inheriting classes.
888 *
889 * This function is intended to allow external completion
890 * implementations to set completed text appropriately. It
891 * is mostly relevant when the completion mode is set to
892 * CompletionAuto and CompletionManual modes. See
893 * KCompletionBase::setCompletedText.
894 * Does nothing in CompletionPopup mode, as all available
895 * matches will be shown in the popup.
896 *
897 * @param text the completed text to be set in the widget.
898 */
899 virtual void setCompletedText( const QString& text ) = 0;
900
901 /**
902 * A pure virtual function that must be implemented by
903 * all inheriting classes.
904 * @param items the list of completed items
905 * @param autoSuggest if @c true, the first element of @p items
906 * is auto-completed (i.e. pre-selected).
907 */
908 virtual void setCompletedItems( const QStringList& items, bool autoSuggest =true ) = 0;
909
910 /**
911 * Returns a pointer to the completion object.
912 *
913 * This method is only different from completionObject()
914 * in that it does not create a new KCompletion object even if
915 * the internal pointer is @c NULL. Use this method to get the
916 * pointer to a completion object when inheriting so that you
917 * won't inadvertently create it!!
918 *
919 * @return the completion object or @c NULL if one does not exist.
920 */
921 KCompletion* compObj() const;
922
923protected:
924 /**
925 * Returns a key-binding map.
926 *
927 * This method is the same as getKeyBinding() except it
928 * returns the whole keymap containing the key-bindings.
929 *
930 * @return the key-binding used for the feature given by @p item.
931 */
932 KeyBindingMap getKeyBindings() const;
933
934 /**
935 * Sets or removes the delegation object. If a delegation object is
936 * set, all function calls will be forwarded to the delegation object.
937 * @param delegate the delegation object, or 0 to remove it
938 */
939 void setDelegate( KCompletionBase *delegate );
940
941 /**
942 * Returns the delegation object.
943 * @return the delegation object, or 0 if there is none
944 * @see setDelegate()
945 */
946 KCompletionBase *delegate() const;
947
948private:
949 // This method simply sets the autodelete boolean for
950 // the completion object, the emit signals and handle
951 // signals internally flags to the provided values.
952 void setup( bool, bool, bool );
953
954 // BCI
955protected:
956 /** Virtual hook, used to add new "virtual" functions while maintaining
957 binary compatibility. Unused in this class.
958 */
959 virtual void virtual_hook( int id, void* data );
960private:
961 Q_DISABLE_COPY( KCompletionBase )
962 KCompletionBasePrivate * const d;
963};
964
965#endif // KCOMPLETION_H
966