kdecore Library API Documentation

KCompletion Class Reference

A generic class for completing QStrings. More...

#include <kcompletion.h>

Inheritance diagram for KCompletion:

QObject List of all members.

Public Types

enum  CompOrder { Sorted, Insertion, Weighted }

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

Public Methods

 KCompletion ()
virtual ~KCompletion ()
virtual QString makeCompletion (const QString &string)
QStringList substringCompletion (const QString &string) const
QString previousMatch ()
QString nextMatch ()
virtual const QStringlastMatch () const
QStringList items () const
virtual void setCompletionMode (KGlobalSettings::Completion mode)
KGlobalSettings::Completion completionMode () const
virtual void setOrder (CompOrder order)
CompOrder order () const
virtual void setIgnoreCase (bool ignoreCase)
bool ignoreCase () const
QStringList allMatches ()
QStringList allMatches (const QString &string)
KCompletionMatches allWeightedMatches ()
KCompletionMatches allWeightedMatches (const QString &string)
virtual void setEnableSounds (bool enable)
bool isSoundsEnabled () const
bool hasMultipleMatches () const
void enableSounds ()
void disableSounds ()

Protected Methods

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>
Version:
Id:
kcompletion.h,v 1.73 2003/10/06 07:45:39 bhards Exp

Definition at line 133 of file kcompletion.h.


Member Enumeration Documentation

enum KCompletion::CompOrder
 

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

Enumeration values:
Sorted  Use order of insertion.
Insertion  Use alphabetically sorted order.
Weighted  Use weighted order.

Definition at line 146 of file kcompletion.h.

Referenced by order().


Constructor & Destructor Documentation

KCompletion::KCompletion  
 

Constructor, nothing special here :).

Definition at line 41 of file kcompletion.cpp.

References KGlobalSettings::completionMode(), Insertion, and setOrder().

KCompletion::~KCompletion   [virtual]
 

Destructor, nothing special here, either.

Definition at line 54 of file kcompletion.cpp.


Member Function Documentation

QString KCompletion::makeCompletion const QString   string [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.

Parameters:
string  the string to complete
Returns:
the matching item, or QString::null if there is no matching item.
See also:
slotMakeCompletion , substringCompletion

Reimplemented in KShellCompletion, and KURLCompletion.

Definition at line 186 of file kcompletion.cpp.

References KStdAccel::completion(), KGlobalSettings::CompletionNone, KGlobalSettings::CompletionPopup, KGlobalSettings::CompletionPopupAuto, KGlobalSettings::CompletionShell, QString::isEmpty(), QString::isNull(), match(), matches(), multipleMatches(), postProcessMatch(), and postProcessMatches().

Referenced by slotMakeCompletion().

QStringList KCompletion::substringCompletion const QString   string const
 

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

Parameters:
string  the string to complete
Returns:
a list of items which all contain text as a substring, i.e. not necessarily at the beginning.
See also:
makeCompletion

Definition at line 248 of file kcompletion.cpp.

References QString::find(), QString::isEmpty(), matches(), postProcessMatch(), postProcessMatches(), and Weighted.

QString KCompletion::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()).

Returns:
the next item from the matching-items-list. When there is no match, QString::null is returned and a sound is be issued.
See also:
slotPreviousMatch

Definition at line 376 of file kcompletion.cpp.

References KStdAccel::completion(), match(), matches(), and postProcessMatch().

Referenced by slotPreviousMatch().

QString KCompletion::nextMatch  
 

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

Returns:
the next item from the matching-items-list. When there is no match, QString::null is returned and a sound is issued
See also:
slotNextMatch

Definition at line 343 of file kcompletion.cpp.

References KStdAccel::completion(), match(), matches(), and postProcessMatch().

Referenced by slotNextMatch().

virtual const QString& KCompletion::lastMatch   const [inline, virtual]
 

Returns the last match.

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

Returns:
the last match. QString::null is returned when there is no last match.

Definition at line 225 of file kcompletion.h.

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.

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

Definition at line 93 of file kcompletion.cpp.

References Weighted.

void KCompletion::setCompletionMode KGlobalSettings::Completion    mode [virtual]
 

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.

Parameters:
mode  the completion mode
See also:
completionMode , KGlobalSettings::completionMode

Definition at line 287 of file kcompletion.cpp.

References KGlobalSettings::Completion.

KGlobalSettings::Completion KCompletion::completionMode   const [inline]
 

Return the current completion mode.

May be different from KGlobalSettings::completionMode(), if you explicitly called setCompletionMode().

Returns:
the current completion mode
See also:
setCompletionMode

Definition at line 265 of file kcompletion.h.

References KGlobalSettings::Completion.

void KCompletion::setOrder CompOrder    order [virtual]
 

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.

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.

Parameters:
order  the new order
See also:
order

Definition at line 60 of file kcompletion.cpp.

References order(), and Weighted.

Referenced by KCompletion().

CompOrder KCompletion::order   const [inline]
 

Returns the completion order.

Returns:
the current completion order.
See also:
setOrder

Definition at line 296 of file kcompletion.h.

References CompOrder.

Referenced by setOrder().

void KCompletion::setIgnoreCase bool    ignoreCase [virtual]
 

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

Parameters:
ignoreCase  true to ignore the case
See also:
ignoreCase

Definition at line 66 of file kcompletion.cpp.

References ignoreCase().

bool KCompletion::ignoreCase   const [inline]
 

Return whether KCompletion acts case insensitively or not.

Default is false (case sensitive).

Returns:
true if the case will be ignored
See also:
setIgnoreCase

Definition at line 313 of file kcompletion.h.

Referenced by setIgnoreCase().

QStringList KCompletion::allMatches  
 

Returns a list of all items matching the last completed string.

Might take some time, when you have LOTS of items.

Returns:
a list of all matches for the last completed string.
See also:
substringCompletion

Definition at line 293 of file kcompletion.cpp.

References matches(), postProcessMatches(), and Weighted.

QStringList KCompletion::allMatches const QString   string
 

Returns a list of all items matching string.

Parameters:
string  the string to match
Returns:
the list of all matches

Definition at line 319 of file kcompletion.cpp.

References matches(), postProcessMatches(), and Weighted.

KCompletionMatches KCompletion::allWeightedMatches  
 

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.

Returns:
a list of all completion matches
See also:
substringCompletion

Definition at line 306 of file kcompletion.cpp.

References matches(), postProcessMatches(), and Weighted.

KCompletionMatches KCompletion::allWeightedMatches const QString   string
 

Returns a list of all items matching string.

Parameters:
string  the string to match
Returns:
a list of all matches

Definition at line 329 of file kcompletion.cpp.

References matches(), postProcessMatches(), and Weighted.

virtual void KCompletion::setEnableSounds bool    enable [inline, virtual]
 

Enables/disables playing 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 -> rotation.

For playing the sounds, KNotifyClient() is used.

Parameters:
enable  true to enable sounds
See also:
isSoundsEnabled

Definition at line 364 of file kcompletion.h.

bool KCompletion::isSoundsEnabled   const [inline]
 

Tells you whether KCompletion will play sounds on certain occasions.

Default is enabled.

Returns:
true if sounds are enabled
See also:
enableSounds , disableSounds

Definition at line 373 of file kcompletion.h.

bool KCompletion::hasMultipleMatches   const [inline]
 

Returns true when more than one match is found.

Returns:
true if there are more than one match
See also:
multipleMatches

Definition at line 380 of file kcompletion.h.

void KCompletion::enableSounds   [inline]
 

Deprecated:
See also:
setEnableSounds

Definition at line 387 of file kcompletion.h.

void KCompletion::disableSounds   [inline]
 

Deprecated:
See also:
setEnableSounds

Definition at line 393 of file kcompletion.h.

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 403 of file kcompletion.h.

References makeCompletion().

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 412 of file kcompletion.h.

References previousMatch().

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 421 of file kcompletion.h.

References nextMatch().

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(), and Weighted.

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 103 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 112 of file kcompletion.cpp.

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

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 165 of file kcompletion.cpp.

References KCompTreeNode::remove().

void KCompletion::clear   [virtual, slot]
 

Removes all inserted items.

Definition at line 175 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

Referenced by makeCompletion(), nextMatch(), postProcessMatch(), and previousMatch().

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

Referenced by allMatches(), allWeightedMatches(), makeCompletion(), nextMatch(), postProcessMatches(), previousMatch(), and substringCompletion().

void KCompletion::multipleMatches   [signal]
 

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

See also:
hasMultipleMatches

Referenced by makeCompletion().

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 522 of file kcompletion.h.

References match().

Referenced by makeCompletion(), nextMatch(), previousMatch(), and substringCompletion().

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 534 of file kcompletion.h.

References matches().

Referenced by allMatches(), allWeightedMatches(), makeCompletion(), and substringCompletion().

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 546 of file kcompletion.h.

References matches().


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.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sun May 16 22:01:25 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003