|
|
This class let's you easily use "auto-completion", "manual-completion" or "shell completion" on QString objects. A common use is completing filenames or URLs (see KURLCompletion). But URL-completion is not all, everything should be completable. The user should be able to complete email-addresses, telephone-numbers, commands, SQL queries, ... Everytime 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 LineEdit-widget (KLineEdit), it is even more easy. Basically, you tell a KCompletion-object what strings should be completable and then, whenever the user types something, 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 via the method allMatches().
Notice: auto-completion, shell completion and manual completion work slightly differently:
You don't have to worry much about that though, KCompletion handles that for you, according to the setting setCompletionMode(). The default setting is globally configured by the user and read from KGlobal::completionMode.
A short example:
KCompletion completion; completion.setSorted( true ); 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" ); debug( completion.makeCompletion( "ca" ).local8Bit() ); // In shell-completion-mode, this will be "carp"; in auto-completion- // mode it will return "carp@cs.tu-berlin.de", as that is alphabetically // smaller. // If setSorted was set to false (default), "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 every 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.
KCompletion () |
Constructor, nothing special here :)
~KCompletion () |
Destructor, nothing special here, either.
QString makeCompletion ( const QString& string ) |
Attempts to find an item in the list of available completions, that begins with string. Will either return the first (if more than one match) matching item or QString::null, if no match was found. In the latter case, a beep will be issued, depending on isBeepEnabled(). 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.
Returns: the matching item, or QString::null if there is no matching item.
QString previousMatch () |
Returns: the next item from the matching-items-list When reaching the beginning, the list is rotated, so it will return the last match. When there is no match, QString::null is returned and a beep will be issued, depending on isBeepEnabled().
QString nextMatch () |
Returns: the previous item from the matching-items-list When reaching the last item, the list is rotated, so it will return the first match. When there is no match, QString::null is returned and a beep will be issued, depending on isBeepEnabled().
const QString& lastMatch () |
Returns: the last match. Might be useful if you need to check whether a completion is different from the last one. QString::null is returned when there is no last match.
QStringList items () |
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.
void setCompletionMode ( KGlobal::Completion mode ) |
Sets the completion mode to Auto/Manual (KCompletion documentation), Shell or None. If you don't set the mode explicitly, the global default value KGlobal::completionMode() is used. KGlobal::CompletionNone disables completion.
See also: completionMode, completionMode
KGlobal::Completion completionMode () |
Returns: the current completion mode. May be different from KGlobal::completionMode(), if you explicitly called setCompletionMode().
void setSorted ( bool enable ) |
Setting this to true makes us go into sorted mode (doh). Completion will then always return the alphabetically first match. If set to false, the order is the same as the items were inserted. Note: this only affects new inserted items, already existing items will stay in the current order. So you probably want to call setSorted( true ) before inserting items, when you want everything sorted. Default is false, not sorted.
bool isSorted () |
Returns: true if the completion-items are alphabetically sorted and false if the order of insertion is used.
QStringList allMatches () |
Returns: a list of all matching items. Might take some time, when you have LOTS of items.
void enableSounds () |
Enables playing a sound when
Sounds are only played in shell-completion mode. Default is enabled
See also: disableSounds, isSoundEnabled
void disableSounds () |
Disables playing a sound when
Sounds are only played in shell-completion mode. Default is enabled
See also: enableSounds, isSoundEnabled
bool isSoundsEnabled () |
Tells you whether KCompletion will issue beeps (KApplication::beep()) Beeps only in manual-completion mode Default is enabled
See also: enableSounds, disableSounds
void slotMakeCompletion ( const QString& string ) |
Attempts to complete "string" and emits the completion via match(). Same as makeCompletion() (just as a slot).
void slotPreviousMatch () |
Searches the previous matching item and emits it via match() Same as previousMatch() (just as a slot).
void slotNextMatch () |
Searches the next matching item and emits it via match() Same as nextMatch() (just as a slot).
bool hasMultipleMatches () |
Returns: true when more than one match is found
void setItems ( const QStringList& ) |
Sets the list of items available for completion. Removes all previous items.
void addItem ( const QString& ) |
Adds an item to the list of available completions. Resets the current item-state (previousMatch() and nextMatch() won't work anymore).
void removeItem ( const QString& ) |
Removes an item from the list of available completions. Resets the current item-state (previousMatch() and nextMatch() won't work anymore).
void clear () |
Clears the list of inserted items.
void match ( const QString& ) |
The matching item. Will be emitted by makeCompletion(), previousMatch() or nextMatch(). May be QString::null if there is no matching item.
void matches ( const QStringList& ) |
All matching items. Will be emitted by makeCompletion() in shell- completion-mode, when the same string is passed to makeCompletion twice or more often.
void multipleMatches () |
This signal is emitted, when calling makeCompletion() and more than one matching item is found.