class KCompletion

A generic class for completing QStrings. More...

Definition#include <kcompletion.h>
InheritsQObject (qt) [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Types

Public Methods

Public Slots

Signals

Protected Methods


Detailed Description

This class offers easy use of "auto-completion", "manual-completion" or "shell completion" on QString objects. 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, ... 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 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:

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 KGlobalSettings::completionMode().

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.

enum CompOrder { Sorted, Insertion, Weighted }

CompOrder

Constants that represent the order in which KCompletion performs completion-lookups.

 KCompletion ()

KCompletion

Constructor, nothing special here :)

 ~KCompletion ()

~KCompletion

[virtual]

Destructor, nothing special here, either.

QString  makeCompletion ( const QString& string )

makeCompletion

[virtual]

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

Returns: the matching item, or QString::null if there is no matching item.

See also: slotMakeCompletion

QString  previousMatch ()

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 and a sound is issued (depending on isSoundsEnabled()). When there is no match, QString::null is returned and a sound is be issued.

See also: slotPreviousMatch

QString  nextMatch ()

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 and a sound is issued (depending on isSoundsEnabled()). When there is no match, QString::null is returned and a sound is issued.

See also: slotNextMatch

const QString&  lastMatch ()

lastMatch

[const virtual]

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

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.

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

Returns: a list of all items

See also: setItems

void  setCompletionMode ( KGlobalSettings::Completion mode )

setCompletionMode

Sets the completion mode to Auto/Manual (see KCompletion documentation), Shell or None. If you don't set the mode explicitly, the global default value KGlobalSettings::completionMode() is used. KGlobalSettings::CompletionNone disables completion.

See also: completionMode, completionMode

KGlobalSettings::Completion  completionMode ()

completionMode

[const]

Returns: the current completion mode. May be different from KGlobalSettings::completionMode(), if you explicitly called setCompletionMode().

See also: setCompletionMode

void  setOrder ( CompOrder order )

setOrder

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 webbrowser 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

See also: order

CompOrder  order ()

order

[const]

Returns: the current completion order.

See also: setOrder

QStringList  allMatches ()

allMatches

Returns: a list of all items matching the last completed string. Might take some time, when you have LOTS of items.

QStringList  allMatches ( const QString& string )

allMatches

Returns: a list of all items matching string.

void  enableSounds ()

enableSounds

Enables playing a sound when

For playing the sounds, KNotifyClient() is used.

See also: disableSounds, isSoundsEnabled

void  disableSounds ()

disableSounds

Disables playing sounds. Default is enabled

See also: enableSounds, isSoundsEnabled

bool  isSoundsEnabled ()

isSoundsEnabled

[const]

Tells you whether KCompletion will play sounds on certain occasions. Default is enabled

See also: enableSounds, disableSounds

bool  hasMultipleMatches ()

hasMultipleMatches

[const]

Returns: true when more than one match is found

See also: multipleMatches

void  slotMakeCompletion ( const QString& string )

slotMakeCompletion

[slot]

Attempts to complete "string" and emits the completion via match(). Same as makeCompletion() (just as a slot).

See also: makeCompletion

void  slotPreviousMatch ()

slotPreviousMatch

[slot]

Searches the previous matching item and emits it via match() Same as previousMatch() (just as a slot).

See also: previousMatch

void  slotNextMatch ()

slotNextMatch

[slot]

Searches the next matching item and emits it via match() Same as nextMatch() (just as a slot).

See also: nextMatch

void  insertItems ( const QStringList& items )

insertItems

[slot]

Inserts items into the list of possible completions. Does the same as setItems(), but does not call clear() before.

void  setItems ( const QStringList& )

setItems

[slot]

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

See also: items

void  addItem ( const QString& )

addItem

[slot]

Adds an item to the list of available completions. Resets the current item-state (previousMatch() and nextMatch() won't work anymore).

void  addItem ( const QString&, uint weight )

addItem

[slot]

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 weight or adds it to the current weighting if the item is already available. The weight has to be greater than 1 to take effect (default weight is 1).

void  removeItem ( const QString& )

removeItem

[slot]

Removes an item from the list of available completions. Resets the current item-state (previousMatch() and nextMatch() won't work anymore).

void  clear ()

clear

[slot]

Removes all inserted items.

void  match ( const QString& )

match

[signal]

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

matches

[signal]

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

multipleMatches

[signal]

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

See also: hasMultipleMatches

void  postProcessMatch ( QString * )

postProcessMatch

[protected virtual]

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.

See also: postProcessMatches

void  postProcessMatches ( QStringList * )

postProcessMatches

[protected virtual]

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.

See also: postProcessMatch