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;

Member Function Documentation

KCompletion::KCompletion()

Constructor, nothing special here :)

[slot] void KCompletion::addItem(const QString &item)

Adds an item to the list of available completions. Resets the current item state (previousMatch() and nextMatch() won't work the next time they are called).

item the item to add

[slot] void KCompletion::addItem(const QString &item, uint weight)

Adds an item to the list of available completions. Resets the current item state (previousMatch() and nextMatch() won't work the next time they are called).

Sets the weight of the item to weight or adds it to the current weight if the item is already available. The weight has to be greater than 1 to take effect (default weight is 1).

item the item to add

weight the weight of the item, default is 1

QStringList KCompletion::allMatches()

Returns a list of all items matching the last completed string. It might take some time if you have a lot of items.

See also substringCompletion.

QStringList KCompletion::allMatches(const QString &string)

Returns a list of all items matching string.

KCompletionMatches KCompletion::allWeightedMatches()

Returns a list of all items matching the last completed string. It might take some time if you have a lot 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.

See also substringCompletion.

KCompletionMatches KCompletion::allWeightedMatches(const QString &string)

Returns a list of all items matching string.

[virtual slot] void KCompletion::clear()

Removes all inserted items.

KCompletion::CompletionMode KCompletion::completionMode() const

Returns the current completion mode, default is CompletionPopup

See also setCompletionMode and CompletionMode.

bool KCompletion::hasMultipleMatches() const

Returns true when more than one match is found.

See also multipleMatches.

bool KCompletion::ignoreCase() const

Returns whether KCompletion acts case insensitively or not.

Default is false (case sensitive).

See also setIgnoreCase.

[slot] void KCompletion::insertItems(const QStringList &items)

Inserts items into the list of possible completions.

It does the same as setItems(), but without calling clear() before.

items the items to insert

bool KCompletion::isEmpty() const

Returns true if the completion object contains no entries.

QStringList KCompletion::items() const

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.

See also setItems.

[virtual] const QString &KCompletion::lastMatch() const

Returns the last match. Might be useful if you need to check whether a completion is different from the last one.

QString() is returned when there is no last match.

[virtual slot] QString KCompletion::makeCompletion(const QString &string)

Attempts to find an item in the list of available completions that begins with string. Will either return the first matching item (if there is more than one match) or QString(), if no match is found.

In the latter case, a sound will be emitted, depending on soundsEnabled(). If a match is found, it will be emitted via the signal match().

If this is called twice or more 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.

string the string to complete

Returns the matching item, or QString() if there is no matching item.

See also substringCompletion.

[signal] void KCompletion::match(const QString &item)

This signal is emitted when a match is found.

In particular, makeCompletion(), previousMatch() and nextMatch() all emit this signal; makeCompletion() will only emit it when a match is found, but the other methods will always emit it (and so may emit it with an empty string).

item the matching item, or QString() if there were no more matching items.

[signal] void KCompletion::matches(const QStringList &matchlist)

This signal is emitted by makeCompletion() in shell-completion mode when the same string is passed to makeCompletion() multiple times in a row.

matchlist the list of all matching items

[signal] void KCompletion::multipleMatches()

This signal is emitted when calling makeCompletion() and more than one matching item is found.

See also hasMultipleMatches.

[slot] QString KCompletion::nextMatch()

Returns the next item from the list of matching items.

When reaching the last item, the list is rotated, so it will return the first match and a sound is emitted (depending on soundsEnabled()).

Returns the next item from the list of matching items. When there is no match, QString() is returned and a sound is emitted.

KCompletion::CompOrder KCompletion::order() const

Returns the completion order.

See also setOrder.

[virtual protected] void KCompletion::postProcessMatch(QString *match) const

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.

match the match to process

See also postProcessMatches.

[virtual protected] void KCompletion::postProcessMatches(KCompletionMatches *matches) const

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.

matches the matches to process

See also postProcessMatch.

[virtual protected] void KCompletion::postProcessMatches(QStringList *matchList) const

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.

matchList the matches to process

See also postProcessMatch.

[slot] QString KCompletion::previousMatch()

Returns the next item from the list of matching items.

When reaching the beginning, the list is rotated so it will return the last match and a sound is emitted (depending on soundsEnabled()).

Returns the next item from the list of matching items. When there is no match, QString() is returned and a sound is emitted.

[slot] void KCompletion::removeItem(const QString &item)

Removes an item from the list of available completions. Resets the current item state (previousMatch() and nextMatch() won't work the next time they are called).

item the item to remove

[virtual] void KCompletion::setCompletionMode(KCompletion::CompletionMode mode)

Sets the completion mode.

mode the completion mode

See also completionMode() and CompletionMode.

[virtual] void KCompletion::setIgnoreCase(bool ignoreCase)

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).

ignoreCase true to ignore the case

See also ignoreCase.

[virtual slot] void KCompletion::setItems(const QStringList &itemList)

Sets the list of items available for completion. Removes all previous items.

itemList the list of items that are available for completion

See also items.

[virtual] void KCompletion::setOrder(KCompletion::CompOrder order)

KCompletion offers three different ways in which it offers its items:

• in the order of insertion
• sorted alphabetically
• weighted

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.

Default is insertion order.

order the new order

See also order.

[protected, since 5.87] void KCompletion::setShouldAutoSuggest(bool shouldAutosuggest)

Deriving classes may set this property and control whether the auto-suggestion should be displayed for the last completion operation performed.

Applies for CompletionPopupAuto and CompletionAuto modes.

This function was introduced in 5.87.

See also shouldAutoSuggest().

[protected, since 5.88] void KCompletion::setSorterFunction(KCompletion::SorterFunction sortFunc)

Sets a custom function to be used to sort the matches. Can be set to nullptr to use the default sorting logic.

Applies for CompOrder::Sorted mode.

This function was introduced in 5.88.

[virtual] void KCompletion::setSoundsEnabled(bool enable)

Enables/disables emitting a sound when

• makeCompletion() can't find a match
• there is a partial completion (= multiple matches in Shell-completion mode)
• nextMatch() or previousMatch() hit the last possible match and the list is rotated

KNotifyClient() is used to emit the sounds.

enable true to enable sounds

See also soundsEnabled.

[since 5.87] bool KCompletion::shouldAutoSuggest() const

Informs the caller if they should display the auto-suggestion for the last completion operation performed.

Applies for CompletionPopupAuto and CompletionAuto modes.

Defaults to true, but deriving classes may set it to false in special cases via "setShouldAutoSuggest".

Returns true if auto-suggestion should be displayed for the last completion operation performed.

This function was introduced in 5.87.

See also setShouldAutoSuggest().

bool KCompletion::soundsEnabled() const

Tells you whether KCompletion will emit sounds on certain occasions.

Default is enabled.

Returns true if sounds are enabled

See also setSoundsEnabled.

QStringList KCompletion::substringCompletion(const QString &string) const

Returns a list of all completion items that contain the given string. string the string to complete

Returns a list of items which contain text as a substring, i.e. not necessarily at the beginning.

See also makeCompletion.