class KCompletion


Module kdeui
Namespace
Class KCompletion
Inherits QObject
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:

  • 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, KCompletion needs to know whether to deliver partial matches (shell completion) or whole matches (auto/manual completion), therefore KGlobalSettings.CompletionMan and KGlobalSettings.CompletionAuto have the exact same effect in KCompletion.

  • 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, 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



    enums

    enum details

    methods