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 | |
34 | class KCompTreeNode; |
35 | class KCompletionPrivate; |
36 | class KCompletionBasePrivate; |
37 | class KCompletionMatchesWrapper; |
38 | class 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 | */ |
130 | class 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 | |
138 | public: |
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 | |
379 | public 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 | |
469 | Q_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 | |
493 | protected: |
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 | |
533 | private: |
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 ( const KCompTreeNode *, |
541 | const QString& beginning, |
542 | KCompletionMatchesWrapper *matches, |
543 | bool addWeight = false ) const; |
544 | void ( 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 | |
552 | private: |
553 | Q_DISABLE_COPY( KCompletion ) |
554 | KCompletionPrivate* const d; |
555 | }; |
556 | |
557 | // some more helper stuff |
558 | typedef KSortableList<QString> KCompletionMatchesList; |
559 | class 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 | */ |
579 | class KDEUI_EXPORT KCompletionMatches : public KCompletionMatchesList |
580 | { |
581 | public: |
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 | |
627 | private: |
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 | */ |
645 | class KDEUI_EXPORT KCompletionBase |
646 | { |
647 | public: |
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 | |
923 | protected: |
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 | |
948 | private: |
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 |
955 | protected: |
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 ); |
960 | private: |
961 | Q_DISABLE_COPY( KCompletionBase ) |
962 | KCompletionBasePrivate * const d; |
963 | }; |
964 | |
965 | #endif // KCOMPLETION_H |
966 | |