kdecore Library API Documentation

KCompletion Class Reference

A generic class for completing QStrings. More...

#include <kcompletion.h>

Inheritance diagram for KCompletion:

Inheritance graph
[legend]
Collaboration diagram for KCompletion:

Collaboration graph
[legend]
List of all members.

Public Slots

void slotMakeCompletion (const QString &string)
void slotPreviousMatch ()
void slotNextMatch ()
void insertItems (const QStringList &items)
virtual void setItems (const QStringList &list)
void addItem (const QString &item)
void addItem (const QString &item, uint weight)
void removeItem (const QString &item)
virtual void clear ()

Signals

void match (const QString &item)
void matches (const QStringList &matchlist)
void multipleMatches ()

Protected Member Functions

virtual void postProcessMatch (QString *match) const
virtual void postProcessMatches (QStringList *matches) const
virtual void postProcessMatches (KCompletionMatches *matches) const
virtual void virtual_hook (int id, void *data)

Detailed Description

A generic class for completing QStrings.

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

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.

Author:
Carsten Pfeiffer <pfeiffer@kde.org>

Definition at line 132 of file kcompletion.h.


Member Function Documentation

void KCompletion::slotMakeCompletion const QString string  )  [inline, slot]
 

Attempts to complete "string" and emits the completion via match().

Same as makeCompletion() (just as a slot).

Parameters:
string the string to complete
See also:
makeCompletion

Definition at line 407 of file kcompletion.h.

void KCompletion::slotPreviousMatch  )  [inline, slot]
 

Searches the previous matching item and emits it via match().

Same as previousMatch() (just as a slot).

See also:
previousMatch

Definition at line 416 of file kcompletion.h.

void KCompletion::slotNextMatch  )  [inline, slot]
 

Searches the next matching item and emits it via match().

Same as nextMatch() (just as a slot).

See also:
nextMatch

Definition at line 425 of file kcompletion.h.

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

Inserts items into the list of possible completions.

Does the same as setItems(), but does not call clear() before.

Parameters:
items the items to insert

Definition at line 78 of file kcompletion.cpp.

References addItem().

Referenced by setItems().

void KCompletion::setItems const QStringList list  )  [virtual, 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().

Parameters:
list the list of items that are available for completion
See also:
items

Definition at line 71 of file kcompletion.cpp.

References clear(), and insertItems().

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

Adds an item to the list of available completions.

Resets the current item-state ( previousMatch() and nextMatch() won't work anymore).

Parameters:
item the item to add

Definition at line 106 of file kcompletion.cpp.

Referenced by insertItems().

void KCompletion::addItem const QString item,
uint  weight
[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).

Parameters:
item the item to add
weight the weight of the item, default is 1

Definition at line 115 of file kcompletion.cpp.

References QString::at(), KCompTreeNode::confirm(), KCompTreeNode::insert(), QString::isEmpty(), and QString::length().

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

Removes an item from the list of available completions.

Resets the current item-state ( previousMatch() and nextMatch() won't work anymore).

Parameters:
item the item to remove

Definition at line 168 of file kcompletion.cpp.

References KCompTreeNode::remove().

void KCompletion::clear  )  [virtual, slot]
 

Removes all inserted items.

Definition at line 178 of file kcompletion.cpp.

Referenced by setItems().

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

The matching item.

Will be emitted by makeCompletion(), previousMatch() or nextMatch(). May be QString::null if there is no matching item.

Parameters:
item the match, or QString::null if there is none

void KCompletion::matches const QStringList matchlist  )  [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.

Parameters:
matchlist the list of matches

void KCompletion::multipleMatches  )  [signal]
 

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

See also:
hasMultipleMatches

virtual void KCompletion::postProcessMatch QString match  )  const [inline, 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.

Parameters:
match the match to process
See also:
postProcessMatches

Reimplemented in KShellCompletion, and KURLCompletion.

Definition at line 528 of file kcompletion.h.

virtual void KCompletion::postProcessMatches QStringList matches  )  const [inline, 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.

Parameters:
matches the matches to process
See also:
postProcessMatch

Reimplemented in KShellCompletion, and KURLCompletion.

Definition at line 540 of file kcompletion.h.

virtual void KCompletion::postProcessMatches KCompletionMatches matches  )  const [inline, 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.

Parameters:
matches the matches to process
See also:
postProcessMatch

Reimplemented in KShellCompletion, and KURLCompletion.

Definition at line 552 of file kcompletion.h.


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdecore Library Version 3.4.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Thu Jul 20 12:29:13 2006 by doxygen 1.4.4 written by Dimitri van Heesch, © 1997-2003