KCompletion

Search for usage in LXR

#include <KCompletion>

Inheritance diagram for KCompletion:

Public Types

enum  CompletionMode {
  CompletionNone = 1, CompletionAuto, CompletionMan, CompletionShell,
  CompletionPopup, CompletionPopupAuto
}
 
enum  CompOrder { Sorted, Insertion, Weighted }
 

Properties

bool ignoreCase
 
QStringList items
 
CompOrder order
 
- Properties inherited from QObject
 objectName
 

Signals

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

Public Slots

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

Public Member Functions

 KCompletion ()
 
virtual ~KCompletion ()
 
QStringList allMatches ()
 
QStringList allMatches (const QString &string)
 
KCompletionMatches allWeightedMatches ()
 
KCompletionMatches allWeightedMatches (const QString &string)
 
CompletionMode completionMode () const
 
bool hasMultipleMatches () const
 
bool ignoreCase () const
 
bool isEmpty () const
 
QStringList items () const
 
virtual const QStringlastMatch () const
 
CompOrder order () const
 
virtual void setCompletionMode (CompletionMode mode)
 
virtual void setIgnoreCase (bool ignoreCase)
 
virtual void setOrder (CompOrder order)
 
virtual void setSoundsEnabled (bool enable)
 
bool soundsEnabled () const
 
QStringList substringCompletion (const QString &string) const
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 

Protected Member Functions

virtual void postProcessMatch (QString *match) const
 
virtual void postProcessMatches (QStringList *matchList) const
 
virtual void postProcessMatches (KCompletionMatches *matches) const
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 

Additional Inherited Members

- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QObject
typedef QObjectList
 

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

  • auto completion always returns a complete item as match. When more than one matching item is available, it will deliver just the first one (depending on sorting order). 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, except that it is not 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. KCompletion needs to know whether to deliver partial matches (shell completion) or whole matches (auto/manual completion), therefore KCompletion::CompletionMan and KCompletion::CompletionAuto have the exact same effect in KCompletion.
  • shell completion works like "tab completion" in a shell: 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().

As an application programmer, you do not normally have to worry about the different completion modes; KCompletion handles that for you, according to the setting setCompletionMode(). The default setting is globally configured by the user and read from completionMode().

A short example:

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 null), as this is used internally as a delimiter.

You may inherit from KCompletion and override makeCompletion() in special cases (like reading directories or urls and then supplying the contents to KCompletion, as KUrlCompletion does), but this is usually not necessary.

Author
Carsten Pfeiffer pfeif[email protected][email protected][email protected]kde.o[email protected]rg

Definition at line 116 of file kcompletion.h.

Member Enumeration Documentation

This enum describes the completion mode used for by the KCompletion class.

Since
5.0
Enumerator
CompletionNone 

No completion is used.

CompletionAuto 

Text is automatically filled in whenever possible.

CompletionMan 

Same as automatic, but shortest match is used for completion.

CompletionShell 

Completes text much in the same way as a typical *nix shell would.

CompletionPopup 

Lists all possible matches in a popup list box to choose from.

CompletionPopupAuto 

Lists all possible matches in a popup list box to choose from, and automatically fills the result whenever possible.

Definition at line 130 of file kcompletion.h.

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

Enumerator
Sorted 

Use alphabetically sorted order.

Insertion 

Use order of insertion.

Weighted 

Use weighted order.

Definition at line 162 of file kcompletion.h.

Constructor & Destructor Documentation

KCompletion::KCompletion ( )

Constructor, nothing special here :)

Definition at line 128 of file kcompletion.cpp.

KCompletion::~KCompletion ( )
virtual

Destructor, nothing special here, either.

Definition at line 136 of file kcompletion.cpp.

Member Function Documentation

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 the next time they are called).

Parameters
itemthe item to add

Definition at line 215 of file kcompletion.cpp.

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

Parameters
itemthe item to add
weightthe weight of the item, default is 1

Definition at line 225 of file kcompletion.cpp.

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.

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

Definition at line 377 of file kcompletion.cpp.

QStringList KCompletion::allMatches ( const QString string)

Returns a list of all items matching string.

Parameters
stringthe string to match
Returns
the list of all matches

Definition at line 405 of file kcompletion.cpp.

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.

Returns
a list of all completion matches
See also
substringCompletion

Definition at line 391 of file kcompletion.cpp.

KCompletionMatches KCompletion::allWeightedMatches ( const QString string)

Returns a list of all items matching string.

Parameters
stringthe string to match
Returns
a list of all matches

Definition at line 416 of file kcompletion.cpp.

void KCompletion::clear ( )
virtualslot

Removes all inserted items.

Reimplemented in PimCommon::KMailCompletion.

Definition at line 266 of file kcompletion.cpp.

KCompletion::CompletionMode KCompletion::completionMode ( ) const

Returns the current completion mode.

Returns
the current completion mode, default is CompletionPopup
See also
setCompletionMode
CompletionMode

Definition at line 371 of file kcompletion.cpp.

bool KCompletion::hasMultipleMatches ( ) const

Returns true when more than one match is found.

Returns
true if there is more than one match
See also
multipleMatches

Definition at line 439 of file kcompletion.cpp.

bool KCompletion::ignoreCase ( ) const

Returns whether KCompletion acts case insensitively or not.

Default is false (case sensitive).

Returns
true if the case will be ignored
See also
setIgnoreCase
void KCompletion::insertItems ( const QStringList items)
slot

Inserts items into the list of possible completions.

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

Parameters
itemsthe items to insert

Definition at line 171 of file kcompletion.cpp.

bool KCompletion::isEmpty ( ) const

Returns true if the completion object contains no entries.

Definition at line 197 of file kcompletion.cpp.

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.

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
const QString & KCompletion::lastMatch ( ) const
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() is returned when there is no last match.

Definition at line 480 of file kcompletion.cpp.

QString KCompletion::makeCompletion ( const QString string)
virtualslot

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.

Parameters
stringthe string to complete
Returns
the matching item, or QString() if there is no matching item.
See also
substringCompletion

Reimplemented in PimCommon::KMailCompletion, KShellCompletion, KUrlCompletion, and KateCmdShellCompletion.

Definition at line 277 of file kcompletion.cpp.

void KCompletion::match ( const QString item)
signal

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 alwasy emit it (and so may emit it with an empty string).

Parameters
itemthe matching item, or QString() if there were no more matching items.
void KCompletion::matches ( const QStringList matchlist)
signal

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

Parameters
matchlistthe list of all matching items
void KCompletion::multipleMatches ( )
signal

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

See also
hasMultipleMatches
QString KCompletion::nextMatch ( )
slot

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.

Definition at line 448 of file kcompletion.cpp.

CompOrder KCompletion::order ( ) const

Returns the completion order.

Returns
the current completion order.
See also
setOrder
void KCompletion::postProcessMatch ( QString match) const
protectedvirtual

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
matchthe match to process
See also
postProcessMatches

Definition at line 203 of file kcompletion.cpp.

void KCompletion::postProcessMatches ( QStringList matchList) const
protectedvirtual

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
matchListthe matches to process
See also
postProcessMatch

Reimplemented in PimCommon::KMailCompletion.

Definition at line 207 of file kcompletion.cpp.

void KCompletion::postProcessMatches ( KCompletionMatches matches) const
protectedvirtual

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
matchesthe matches to process
See also
postProcessMatch

Definition at line 211 of file kcompletion.cpp.

QString KCompletion::previousMatch ( )
slot

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.

Definition at line 486 of file kcompletion.cpp.

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 the next time they are called).

Parameters
itemthe item to remove

Definition at line 256 of file kcompletion.cpp.

void KCompletion::setCompletionMode ( CompletionMode  mode)
virtual

Sets the completion mode.

Parameters
modethe completion mode
See also
CompletionMode

Definition at line 365 of file kcompletion.cpp.

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
ignoreCasetrue to ignore the case
See also
ignoreCase

Definition at line 153 of file kcompletion.cpp.

void KCompletion::setItems ( const QStringList itemList)
virtualslot

Sets the list of items available for completion.

Removes all previous items.

Note
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
itemListthe list of items that are available for completion
See also
items

Definition at line 165 of file kcompletion.cpp.

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 if you want everything sorted.

Default is insertion order.

Parameters
orderthe new order
See also
order

Definition at line 140 of file kcompletion.cpp.

void KCompletion::setSoundsEnabled ( bool  enable)
virtual

Enables/disables emitting a sound when.

KNotifyClient() is used to emit the sounds.

Parameters
enabletrue to enable sounds
See also
soundsEnabled

Definition at line 427 of file kcompletion.cpp.

void KCompletion::slotMakeCompletion ( const QString string)
inlineslot

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

Same as makeCompletion(), but in this case as a slot.

Parameters
stringthe string to complete
See also
makeCompletion
Deprecated:
since 5.0, use makeCompletion() instead

Definition at line 401 of file kcompletion.h.

void KCompletion::slotNextMatch ( )
inlineslot

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

Same as nextMatch(), but in this case as a slot.

See also
nextMatch
Deprecated:
since 5.0, use nextMatch() instead

Definition at line 429 of file kcompletion.h.

void KCompletion::slotPreviousMatch ( )
inlineslot

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

Same as previousMatch(), but in this case as a slot.

See also
previousMatch
Deprecated:
since 5.0, use previousMatch() instead

Definition at line 415 of file kcompletion.h.

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

Definition at line 433 of file kcompletion.cpp.

QStringList KCompletion::substringCompletion ( const QString string) const

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

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

Definition at line 334 of file kcompletion.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Wed May 12 2021 22:51:48 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.