#include <kcompletion.h>

Inherits TQObject.

Public Types
enum	CompOrder { Sorted , Insertion , Weighted }

Public Slots
void	slotMakeCompletion (const TQString &string)

void	slotPreviousMatch ()

void	slotNextMatch ()

void	insertItems (const TQStringList &items)

virtual void	setItems (const TQStringList &list)

void	addItem (const TQString &item)

void	addItem (const TQString &item, uint weight)

void	removeItem (const TQString &item)

virtual void	clear ()

Signals
void	match (const TQString &item)

void	matches (const TQStringList &matchlist)

void	multipleMatches ()

Public Member Functions
	TDECompletion ()

virtual	~TDECompletion ()

virtual TQString	makeCompletion (const TQString &string)

TQStringList	substringCompletion (const TQString &string) const

TQString	previousMatch ()

TQString	nextMatch ()

virtual const TQString &	lastMatch () const

TQStringList	items () const

bool	isEmpty () const

virtual void	setCompletionMode (TDEGlobalSettings::Completion mode)

TDEGlobalSettings::Completion	completionMode () const

virtual void	setOrder (CompOrder order)

CompOrder	order () const

virtual void	setIgnoreCase (bool ignoreCase)

bool	ignoreCase () const

TQStringList	allMatches ()

TQStringList	allMatches (const TQString &string)

TDECompletionMatches	allWeightedMatches ()

TDECompletionMatches	allWeightedMatches (const TQString &string)

virtual void	setEnableSounds (bool enable)

bool	isSoundsEnabled () const

bool	hasMultipleMatches () const

void	enableSounds ()

void	disableSounds ()

Protected Member Functions
virtual void	postProcessMatch (TQString *match) const

virtual void	postProcessMatches (TQStringList *matches) const

virtual void	postProcessMatches (TDECompletionMatches *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 TQString 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 TDECompletion, this is very easy, and if you are using a line edit widget ( KLineEdit), it is even more easy. Basically, you tell a TDECompletion 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.

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

auto-completion always returns a complete item as match. When more than one matching items are available, it will deliver just the first (depending on sorting order) item. Iterating over all matches is possible via nextMatch() and previousMatch().

popup-completion works in the same way, the only difference being that the completed items are not put into the edit-widget, but into a separate popup-box.

manual completion works the same way as auto-completion, the subtle difference is, that it isn't invoked automatically while the user is typing, but only when the user presses a special key. The difference of manual and auto-completion is therefore only visible in UI classes, TDECompletion needs to know whether to deliver partial matches (shell completion) or whole matches (auto/manual completion), therefore TDEGlobalSettings::CompletionMan and TDEGlobalSettings::CompletionAuto have the exact same effect in TDECompletion.

shell completion works like how shells complete filenames: when multiple matches are available, the longest possible string of all matches is returned (i.e. only a partial item). Iterating over all matching items (complete, not partial) is possible via nextMatch() and previousMatch().

You don't have to worry much about that though, TDECompletion handles that for you, according to the setting setCompletionMode(). The default setting is globally configured by the user and read from TDEGlobalSettings::completionMode().

A short example:

TDECompletion completion;
completion.setOrder( TDECompletion::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 TDECompletion objects. E.g. imagine an editor like kwrite with multiple open files. You could store items of each file in a different TDECompletion object, so that you know (and tell the user) where a completion comes from.

Note: TDECompletion does not work with strings that contain 0x0 characters (unicode nul), as this is used internally as a delimiter.

You may inherit from TDECompletion and override makeCompletion() in special cases (like reading directories/urls and then supplying the contents to TDECompletion, as KURLCompletion does), but generally, this is not necessary.

Author: Carsten Pfeiffer pfeif.nosp@m.fer@.nosp@m.kde.o.nosp@m.rg

Definition at line 132 of file kcompletion.h.

Member Enumeration Documentation

◆ CompOrder

enum TDECompletion::CompOrder

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

Enumerator
Sorted	Use alphabetically sorted order.
Insertion	Use order of insertion.
Weighted	Use weighted order.

Definition at line 145 of file kcompletion.h.

Constructor & Destructor Documentation

◆ TDECompletion()

TDECompletion::TDECompletion ( )

Constructor, nothing special here :)

Definition at line 41 of file kcompletion.cpp.

◆ ~TDECompletion()

TDECompletion::~TDECompletion ( )

virtual

Destructor, nothing special here, either.

Definition at line 54 of file kcompletion.cpp.

Member Function Documentation

◆ addItem [1/2]

void TDECompletion::addItem ( const TQString & 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.

◆ addItem [2/2]

void TDECompletion::addItem	(	const TQString &	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.

◆ allMatches() [1/2]

TQStringList TDECompletion::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 296 of file kcompletion.cpp.

◆ allMatches() [2/2]

TQStringList TDECompletion::allMatches ( const TQString & string )

Returns a list of all items matching string.

Parameters

string the string to match

Returns: the list of all matches

Definition at line 322 of file kcompletion.cpp.

◆ allWeightedMatches() [1/2]

TDECompletionMatches TDECompletion::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 TDECompletionMatches, 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 309 of file kcompletion.cpp.

◆ allWeightedMatches() [2/2]

TDECompletionMatches TDECompletion::allWeightedMatches ( const TQString & string )

Returns a list of all items matching string.

Parameters

string the string to match

Returns: a list of all matches

Definition at line 332 of file kcompletion.cpp.

◆ clear

void TDECompletion::clear ( )

virtualslot

Removes all inserted items.

Definition at line 178 of file kcompletion.cpp.

◆ completionMode()

TDEGlobalSettings::Completion TDECompletion::completionMode ( ) const

inline

Return the current completion mode.

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

Returns: the current completion mode

See also: setCompletionMode

Definition at line 269 of file kcompletion.h.

◆ disableSounds()

void TDECompletion::disableSounds ( )

inline

Deprecated:

See also: setEnableSounds

Definition at line 397 of file kcompletion.h.

◆ enableSounds()

void TDECompletion::enableSounds ( )

inline

Deprecated:

See also: setEnableSounds

Definition at line 391 of file kcompletion.h.

◆ hasMultipleMatches()

bool TDECompletion::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 384 of file kcompletion.h.

◆ ignoreCase()

bool TDECompletion::ignoreCase ( ) const

inline

Return whether TDECompletion acts case insensitively or not.

Default is false (case sensitive).

Returns: true if the case will be ignored

See also: setIgnoreCase

Definition at line 317 of file kcompletion.h.

◆ insertItems

void TDECompletion::insertItems ( const TQStringList & 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.

◆ isEmpty()

bool TDECompletion::isEmpty ( ) const

Returns true when the completion object contains no entries.

Definition at line 101 of file kcompletion.cpp.

◆ isSoundsEnabled()

bool TDECompletion::isSoundsEnabled ( ) const

inline

Tells you whether TDECompletion will play sounds on certain occasions.

Default is enabled.

Returns: true if sounds are enabled

See also: enableSounds; disableSounds

Definition at line 377 of file kcompletion.h.

◆ items()

TQStringList TDECompletion::items ( ) const

Returns a list of all items inserted into TDECompletion.

This is useful if you need to save the state of a TDECompletion 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( TDECompletion::Insertion ) before calling items().

Returns: a list of all items

See also: setItems

Definition at line 92 of file kcompletion.cpp.

◆ lastMatch()

virtual const TQString& TDECompletion::lastMatch ( ) const

inlinevirtual

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. TQString::null is returned when there is no last match.

Definition at line 224 of file kcompletion.h.

◆ makeCompletion()

TQString TDECompletion::makeCompletion ( const TQString & 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 TQString::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 TQString::null if there is no matching item.

See also: slotMakeCompletion; substringCompletion

Definition at line 189 of file kcompletion.cpp.

◆ match

void TDECompletion::match ( const TQString & item )

signal

The matching item.

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

Parameters

item	the match, or TQString::null if there is none

◆ matches

void TDECompletion::matches ( const TQStringList & 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

◆ multipleMatches

void TDECompletion::multipleMatches ( )

signal

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

See also: hasMultipleMatches

◆ nextMatch()

TQString TDECompletion::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, TQString::null is returned and a sound is issued

See also: slotNextMatch

Definition at line 346 of file kcompletion.cpp.

◆ order()

CompOrder TDECompletion::order ( ) const

inline

Returns the completion order.

Returns: the current completion order.

See also: setOrder

Definition at line 300 of file kcompletion.h.

◆ postProcessMatch()

virtual void TDECompletion::postProcessMatch ( TQString * match ) const

inlineprotectedvirtual

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 TDECompletion. Never delete that pointer!

Default implementation does nothing.

Parameters

match the match to process

See also: postProcessMatches

Definition at line 528 of file kcompletion.h.

◆ postProcessMatches() [1/2]

virtual void TDECompletion::postProcessMatches ( TDECompletionMatches * matches ) const

inlineprotectedvirtual

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

Definition at line 552 of file kcompletion.h.

◆ postProcessMatches() [2/2]

virtual void TDECompletion::postProcessMatches ( TQStringList * matches ) const

inlineprotectedvirtual

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

Definition at line 540 of file kcompletion.h.

◆ previousMatch()

TQString TDECompletion::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, TQString::null is returned and a sound is be issued.

See also: slotPreviousMatch

Definition at line 379 of file kcompletion.cpp.

◆ removeItem

void TDECompletion::removeItem ( const TQString & 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.

◆ setCompletionMode()

void TDECompletion::setCompletionMode ( TDEGlobalSettings::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 TDEGlobalSettings::completionMode() is used. TDEGlobalSettings::CompletionNone disables completion.

Parameters

mode	the completion mode

See also: completionMode; TDEGlobalSettings::completionMode

Definition at line 291 of file kcompletion.cpp.

◆ setEnableSounds()

virtual void TDECompletion::setEnableSounds ( bool enable )

inlinevirtual

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

◆ setIgnoreCase()

void TDECompletion::setIgnoreCase ( bool ignoreCase )

virtual

Setting this to true makes TDECompletion 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.

◆ setItems

void TDECompletion::setItems ( const TQStringList & list )

virtualslot

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

◆ setOrder()

void TDECompletion::setOrder ( CompOrder order )

virtual

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

in the order of insertion
sorted alphabetically
weighted

Choosing weighted makes TDECompletion 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.

◆ slotMakeCompletion

void TDECompletion::slotMakeCompletion ( const TQString & string )

inlineslot

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.

◆ slotNextMatch

void TDECompletion::slotNextMatch ( )

inlineslot

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.

◆ slotPreviousMatch

void TDECompletion::slotPreviousMatch ( )

inlineslot

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.

◆ substringCompletion()

TQStringList TDECompletion::substringCompletion ( const TQString & 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 251 of file kcompletion.cpp.

The documentation for this class was generated from the following files:

tdecore

Public Types

Public Slots

Signals

Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ CompOrder

Constructor & Destructor Documentation

◆ TDECompletion()

◆ ~TDECompletion()

Member Function Documentation

◆ addItem [1/2]

◆ addItem [2/2]

◆ allMatches() [1/2]

◆ allMatches() [2/2]

◆ allWeightedMatches() [1/2]

◆ allWeightedMatches() [2/2]

◆ clear

◆ completionMode()

◆ disableSounds()

◆ enableSounds()

◆ hasMultipleMatches()

◆ ignoreCase()

◆ insertItems

◆ isEmpty()

◆ isSoundsEnabled()

◆ items()

◆ lastMatch()

◆ makeCompletion()

◆ match

◆ matches

◆ multipleMatches

◆ nextMatch()

◆ order()

◆ postProcessMatch()

◆ postProcessMatches() [1/2]

◆ postProcessMatches() [2/2]

◆ previousMatch()

◆ removeItem

◆ setCompletionMode()

◆ setEnableSounds()

◆ setIgnoreCase()

◆ setItems

◆ setOrder()

◆ slotMakeCompletion

◆ slotNextMatch

◆ slotPreviousMatch

◆ substringCompletion()

tdecore

tdecore