KCompletion Class Reference
This class offers easy use of "auto-completion", "manual-completion" or "shell completion" on QString objects. A generic class for completing QStrings. More...
#include <kcompletion.h>
Inheritance diagram for KCompletion:


Public Types | |
enum | CompOrder { Sorted, Insertion, Weighted } |
Constants that represent the order in which KCompletion performs completion-lookups. More... | |
Public Slots | |
void | slotMakeCompletion (const QString &string) |
Attempts to complete "string" and emits the completion via match(). | |
void | slotPreviousMatch () |
Searches the previous matching item and emits it via match(). | |
void | slotNextMatch () |
Searches the next matching item and emits it via match(). | |
void | insertItems (const QStringList &items) |
Inserts items into the list of possible completions. | |
virtual void | setItems (const QStringList &list) |
Sets the list of items available for completion. | |
void | addItem (const QString &item) |
Adds an item to the list of available completions. | |
void | addItem (const QString &item, uint weight) |
Adds an item to the list of available completions. | |
void | removeItem (const QString &item) |
Removes an item from the list of available completions. | |
virtual void | clear () |
Removes all inserted items. | |
Signals | |
void | match (const QString &item) |
The matching item. | |
void | matches (const QStringList &matchlist) |
All matching items. | |
void | multipleMatches () |
This signal is emitted, when calling makeCompletion() and more than one matching item is found. | |
Public Member Functions | |
KCompletion () | |
Constructor, nothing special here :). | |
virtual | ~KCompletion () |
Destructor, nothing special here, either. | |
virtual QString | makeCompletion (const QString &string) |
Attempts to find an item in the list of available completions, that begins with string . | |
QStringList | substringCompletion (const QString &string) const |
Returns a list of all completion items that contain the given string . | |
QString | previousMatch () |
Returns the next item from the matching-items-list. | |
QString | nextMatch () |
Returns the next item from the matching-items-list. | |
virtual const QString & | lastMatch () const |
Returns the last match. | |
QStringList | items () const |
Returns a list of all items inserted into KCompletion. | |
virtual void | setCompletionMode (KGlobalSettings::Completion mode) |
Sets the completion mode to Auto/Manual, Shell or None. | |
KGlobalSettings::Completion | completionMode () const |
Return the current completion mode. | |
virtual void | setOrder (CompOrder order) |
KCompletion offers three different ways in which it offers its items:
| |
CompOrder | order () const |
Returns the completion order. | |
virtual void | setIgnoreCase (bool ignoreCase) |
Setting this to true makes KCompletion behave case insensitively. | |
bool | ignoreCase () const |
Return whether KCompletion acts case insensitively or not. | |
QStringList | allMatches () |
Returns a list of all items matching the last completed string. | |
QStringList | allMatches (const QString &string) |
Returns a list of all items matching string . | |
KCompletionMatches | allWeightedMatches () |
Returns a list of all items matching the last completed string. | |
KCompletionMatches | allWeightedMatches (const QString &string) |
Returns a list of all items matching string . | |
virtual void | setEnableSounds (bool enable) |
Enables/disables playing a sound when
| |
bool | isSoundsEnabled () const |
Tells you whether KCompletion will play sounds on certain occasions. | |
bool | hasMultipleMatches () const |
Returns true when more than one match is found. | |
void | enableSounds () |
This class or method is obsolete, it is provided for compatibility only. | |
void | disableSounds () |
This class or method is obsolete, it is provided for compatibility only. | |
Protected Member Functions | |
virtual void | postProcessMatch (QString *match) const |
This method is called after a completion is found and before the matching string is emitted. | |
virtual void | postProcessMatches (QStringList *matches) const |
This method is called before a list of all available completions is emitted via matches. | |
virtual void | postProcessMatches (KCompletionMatches *matches) const |
This method is called before a list of all available completions is emitted via matches. | |
virtual void | virtual_hook (int id, void *data) |
Detailed Description
This class offers easy use of "auto-completion", "manual-completion" or "shell completion" on QString objects. A generic class for completing QStrings.A common use is completing filenames or URLs (see KURLCompletion()). But it is not limited to URL-completion -- everything should be completable! The user should be able to complete email-addresses, telephone-numbers, commands, SQL queries, ... Every time your program knows what the user can type into an edit-field, you should offer completion. With KCompletion, this is very easy, and if you are using a line edit widget (KLineEdit), it is even more easy. Basically, you tell a KCompletion object what strings should be completable and whenever completion should be invoked, you call makeCompletion(). KLineEdit and (an editable) KComboBox even do this automatically for you.
KCompletion offers the completed string via the signal match() and all matching strings (when the result is ambiguous) via the method allMatches().
Notice: auto-completion, shell completion and manual completion work slightly differently:
- auto-completion always returns a complete item as match. When more than one matching items are available, it will deliver just the first (depending on sorting order) item. Iterating over all matches is possible via nextMatch() and previousMatch().
- popup-completion works in the same way, the only difference being that the completed items are not put into the edit-widget, but into a separate popup-box.
- manual completion works the same way as auto-completion, the subtle difference is, that it isn't invoked automatically while the user is typing, but only when the user presses a special key. The difference of manual and auto-completion is therefore only visible in UI classes, KCompletion needs to know whether to deliver partial matches (shell completion) or whole matches (auto/manual completion), therefore KGlobalSettings::CompletionMan and KGlobalSettings::CompletionAuto have the exact same effect in KCompletion.
- shell completion works like how shells complete filenames: when multiple matches are available, the longest possible string of all matches is returned (i.e. only a partial item). Iterating over all matching items (complete, not partial) is possible via nextMatch() and previousMatch().
A short example:
KCompletion completion; completion.setOrder( KCompletion::Sorted ); completion.addItem( "pfeiffer@kde.org" ); completion.addItem( "coolo@kde.org" ); completion.addItem( "carpdjih@sp.zrz.tu-berlin.de" ); completion.addItem( "carp@cs.tu-berlin.de" );
cout << completion.makeCompletion( "ca" ).latin1() << endl;In shell-completion-mode, this will be "carp"; in auto-completion- mode it will be "carp@cs.tu-berlin.de", as that is alphabetically smaller. If setOrder was set to Insertion, "carpdjih@sp.zrz.tu-berlin.de" would be completed in auto-completion-mode, as that was inserted before "carp@cs.tu-berlin.de".You can dynamically update the completable items by removing and adding them whenever you want. For advanced usage, you could even use multiple KCompletion objects. E.g. imagine an editor like kwrite with multiple open files. You could store items of each file in a different KCompletion object, so that you know (and tell the user) where a completion comes from.
Note: KCompletion does not work with strings that contain 0x0 characters (unicode nul), as this is used internally as a delimiter.
You may inherit from KCompletion and override makeCompletion() in special cases (like reading directories/urls and then supplying the contents to KCompletion, as KURLCompletion does), but generally, this is not necessary.
- Author:
- Carsten Pfeiffer <pfeiffer@kde.org>
- Version:
- Id
- kcompletion.h,v 1.65.2.1 2003/02/09 13:55:28 rnolden Exp
Definition at line 130 of file kcompletion.h.
Member Enumeration Documentation
|
Constants that represent the order in which KCompletion performs completion-lookups.
Definition at line 143 of file kcompletion.h. Referenced by order(). |
Constructor & Destructor Documentation
|
Constructor, nothing special here :).
Definition at line 39 of file kcompletion.cpp. References KGlobalSettings::completionMode(), Insertion, and setOrder(). |
|
Destructor, nothing special here, either.
Definition at line 52 of file kcompletion.cpp. |
Member Function Documentation
|
Attempts to find an item in the list of available completions, that begins with Will either return the first matching item (if there is more than one match) or QString::null, if no match was found. In the latter case, a sound will be issued, depending on isSoundsEnabled(). If a match was found, it will also be emitted via the signal match(). If this is called twice or more often with the same string while no items were added or removed in the meantime, all available completions will be emitted via the signal matches(). This happens only in shell-completion-mode.
Definition at line 184 of file kcompletion.cpp. References KStdAccel::completion(), KGlobalSettings::CompletionNone, KGlobalSettings::CompletionPopup, KGlobalSettings::CompletionPopupAuto, KGlobalSettings::CompletionShell, match(), matches(), multipleMatches(), postProcessMatch(), and postProcessMatches(). Referenced by slotMakeCompletion(). |
|
Returns a list of all completion items that contain the given
Definition at line 246 of file kcompletion.cpp. References QString::find(), QString::isEmpty(), matches(), postProcessMatch(), postProcessMatches(), and Weighted. |
|
Returns the next item from the matching-items-list. When reaching the beginning, the list is rotated so it will return the last match and a sound is issued (depending on isSoundsEnabled()).
Definition at line 374 of file kcompletion.cpp. References KStdAccel::completion(), match(), matches(), and postProcessMatch(). Referenced by slotPreviousMatch(). |
|
Returns the next item from the matching-items-list. When reaching the last item, the list is rotated, so it will return the first match and a sound is issued (depending on isSoundsEnabled()).
Definition at line 341 of file kcompletion.cpp. References KStdAccel::completion(), match(), matches(), and postProcessMatch(). Referenced by slotNextMatch(). |
|
Returns the last match. Might be useful if you need to check whether a completion is different from the last one.
Definition at line 222 of file kcompletion.h. |
|
Returns a list of all items inserted into KCompletion. This is useful if you need to save the state of a KCompletion object and restore it later. Important note: when order() == Weighted, then every item in the stringlist has its weight appended, delimited by a colon. E.g. an item "www.kde.org" might look like "www.kde.org:4", where 4 is the weight. This is necessary so that you can save the items along with its weighting on disk and load them back with setItems(), restoring its weight as well. If you really don't want the appended weightings, call setOrder( KCompletion::Insertion ) before calling items().
Definition at line 91 of file kcompletion.cpp. References Weighted. |
|
Sets the completion mode to Auto/Manual, Shell or None. If you don't set the mode explicitly, the global default value KGlobalSettings::completionMode() is used. KGlobalSettings::CompletionNone disables completion.
Definition at line 285 of file kcompletion.cpp. |
|
Return the current completion mode. May be different from KGlobalSettings::completionMode(), if you explicitly called setCompletionMode().
Definition at line 262 of file kcompletion.h. References KGlobalSettings::Completion. |
|
KCompletion offers three different ways in which it offers its items:
Choosing weighted makes KCompletion perform an implicit weighting based on how often an item is inserted. Imagine a web browser with a location bar, where the user enters URLs. The more often a URL is entered, the higher priority it gets. Note: Setting the order to sorted only affects new inserted items, already existing items will stay in the current order. So you probably want to call setOrder( Sorted ) before inserting items, when you want everything sorted. Default is insertion order.
Definition at line 58 of file kcompletion.cpp. References Weighted. Referenced by KCompletion(). |
|
Returns the completion order.
Definition at line 293 of file kcompletion.h. References CompOrder. |
|
Setting this to true makes KCompletion behave case insensitively. E.g. makeCompletion( "CA" ); might return "carp@cs.tu-berlin.de". Default is false (case sensitive).
Definition at line 64 of file kcompletion.cpp. |
|
Return whether KCompletion acts case insensitively or not. Default is false (case sensitive).
Definition at line 310 of file kcompletion.h. |
|
Returns a list of all items matching the last completed string. Might take some time, when you have LOTS of items.
Definition at line 291 of file kcompletion.cpp. References matches(), postProcessMatches(), and Weighted. |
|
Returns a list of all items matching
Definition at line 317 of file kcompletion.cpp. References matches(), postProcessMatches(), and Weighted. |
|
Returns a list of all items matching the last completed string. Might take some time, when you have LOTS of items. The matches are returned as KCompletionMatches, which also keeps the weight of the matches, allowing you to modify some matches or merge them with matches from another call to allWeightedMatches(), and sort the matches after that in order to have the matches ordered correctly.
Definition at line 304 of file kcompletion.cpp. References matches(), postProcessMatches(), and Weighted. |
|
Returns a list of all items matching
Definition at line 327 of file kcompletion.cpp. References matches(), postProcessMatches(), and Weighted. |
|
Enables/disables playing a sound when
For playing the sounds, KNotifyClient() is used.
Definition at line 361 of file kcompletion.h. |
|
Tells you whether KCompletion will play sounds on certain occasions. Default is enabled.
Definition at line 370 of file kcompletion.h. |
|
Returns true when more than one match is found.
Definition at line 377 of file kcompletion.h. |
|
This class or method is obsolete, it is provided for compatibility only.
Definition at line 384 of file kcompletion.h. |
|
This class or method is obsolete, it is provided for compatibility only.
Definition at line 390 of file kcompletion.h. |
|
Attempts to complete "string" and emits the completion via match(). Same as makeCompletion() (just as a slot).
Definition at line 400 of file kcompletion.h. References makeCompletion(). |
|
Searches the previous matching item and emits it via match(). Same as previousMatch() (just as a slot).
Definition at line 409 of file kcompletion.h. References previousMatch(). |
|
Searches the next matching item and emits it via match(). Same as nextMatch() (just as a slot).
Definition at line 418 of file kcompletion.h. References nextMatch(). |
|
Inserts Does the same as setItems(), but does not call clear() before.
Definition at line 76 of file kcompletion.cpp. References addItem(), and Weighted. Referenced by setItems(). |
|
Sets the list of items available for completion. Removes all previous items. Notice: when order() == Weighted, then the weighting is looked up for every item in the stringlist. Every item should have ":number" appended, where number is an unsigned integer, specifying the weighting. If you don't like this, call setOrder( KCompletion::Insertion ) before calling setItems().
Definition at line 69 of file kcompletion.cpp. References clear(), and insertItems(). |
|
Adds an item to the list of available completions. Resets the current item-state (previousMatch() and nextMatch() won't work anymore).
Definition at line 101 of file kcompletion.cpp. Referenced by insertItems(). |
|
Adds an item to the list of available completions. Resets the current item-state (previousMatch() and nextMatch() won't work anymore).
Sets the weighting of the item to
Definition at line 110 of file kcompletion.cpp. References QString::at(), KCompTreeNode::confirm(), KCompTreeNode::insert(), QString::isEmpty(), QString::length(), Sorted, and Weighted. |
|
Removes an item from the list of available completions. Resets the current item-state (previousMatch() and nextMatch() won't work anymore).
Definition at line 163 of file kcompletion.cpp. References KCompTreeNode::remove(). |
|
Removes all inserted items.
Definition at line 173 of file kcompletion.cpp. Referenced by setItems(). |
|
The matching item. Will be emitted by makeCompletion(), previousMatch() or nextMatch(). May be QString::null if there is no matching item.
Referenced by makeCompletion(), nextMatch(), and previousMatch(). |
|
All matching items. Will be emitted by makeCompletion() in shell- completion-mode, when the same string is passed to makeCompletion twice or more often.
Referenced by allMatches(), allWeightedMatches(), makeCompletion(), nextMatch(), previousMatch(), and substringCompletion(). |
|
This signal is emitted, when calling makeCompletion() and more than one matching item is found.
Referenced by makeCompletion(). |
|
This method is called after a completion is found and before the matching string is emitted. You can override this method to modify the string that will be emitted. This is necessary e.g. in KURLCompletion(), where files with spaces in their names are shown escaped ("filename\ with\ spaces"), but stored unescaped inside KCompletion. Never delete that pointer! Default implementation does nothing.
Definition at line 519 of file kcompletion.h. Referenced by makeCompletion(), nextMatch(), previousMatch(), and substringCompletion(). |
|
This method is called before a list of all available completions is emitted via matches. You can override this method to modify the found items before match() or matches are emitted. Never delete that pointer! Default implementation does nothing.
Definition at line 531 of file kcompletion.h. Referenced by allMatches(), allWeightedMatches(), makeCompletion(), and substringCompletion(). |
|
This method is called before a list of all available completions is emitted via matches. You can override this method to modify the found items before match() or matches() are emitted. Never delete that pointer! Default implementation does nothing.
Definition at line 543 of file kcompletion.h. |
The documentation for this class was generated from the following files: