org.kde.koala

Class KCompletion

public class KCompletion extends QObject

This class offers easy use of "auto-completion", "manual-completion" or "shell completion" on String 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. See KCompletionSignals for signals emitted by KCompletion

    Author: Carsten Pfeiffer

    UNKNOWN: A generic class for completing Strings.

    Field Summary
    static intInsertion
    static intSorted
    Constants that represent the order in which KCompletion performs completion-lookups.
    static intWeighted
    Constructor Summary
    protected KCompletion(Class dummy)
    KCompletion()
    Constructor, nothing special here :)
    Method Summary
    voidaddItem(String item)
    Adds an item to the list of available completions.
    voidaddItem(String item, int weight)
    Adds an item to the list of available completions.
    ArrayListallMatches()
    Returns a list of all items matching the last completed string.
    ArrayListallMatches(String string)
    Returns a list of all items matching string.
    StringclassName()
    voidclear()
    Removes all inserted items.
    intcompletionMode()
    Return the current completion mode.
    voiddispose()
    Delete the wrapped C++ instance ahead of finalize()
    protected voidfinalize()
    Deletes the wrapped C++ instance
    booleanhasMultipleMatches()
    Returns true when more than one match is found.
    booleanignoreCase()
    Return whether KCompletion acts case insensitively or not.
    voidinsertItems(String[] items)
    Inserts items into the list of possible completions.
    booleanisDisposed()
    Has the wrapped C++ instance been deleted?
    booleanisEmpty()
    Returns true when the completion object contains no entries.
    booleanisSoundsEnabled()
    Tells you whether KCompletion will play sounds on certain occasions.
    ArrayListitems()
    Returns a list of all items inserted into KCompletion.
    StringlastMatch()
    Returns the last match.
    StringmakeCompletion(String string)
    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 null, if no match was found.
    QMetaObjectmetaObject()
    StringnextMatch()
    Returns the next item from the matching-items-list.
    intorder()
    Returns the completion order.
    protected voidpostProcessMatch(StringBuffer match)
    This method is called after a completion is found and before the matching string is emitted.
    protected voidpostProcessMatches(String[] matches)
    This method is called before a list of all available completions is emitted via #matches.
    StringpreviousMatch()
    Returns the next item from the matching-items-list.
    voidremoveItem(String item)
    Removes an item from the list of available completions.
    voidsetCompletionMode(int mode)
    Sets the completion mode to Auto/Manual, Shell or None.
    voidsetEnableSounds(boolean enable)
    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.
    voidsetIgnoreCase(boolean ignoreCase)
    Setting this to true makes KCompletion behave case insensitively.
    voidsetItems(String[] list)
    Sets the list of items available for completion.
    voidsetOrder(int order)
    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.
    voidslotMakeCompletion(String string)
    Attempts to complete "string" and emits the completion via match().
    voidslotNextMatch()
    Searches the next matching item and emits it via match().
    voidslotPreviousMatch()
    Searches the previous matching item and emits it via match().
    ArrayListsubstringCompletion(String string)
    Returns a list of all completion items that contain the given string.

    Field Detail

    Insertion

    public static final int Insertion

    Sorted

    public static final int Sorted
    Constants that represent the order in which KCompletion performs completion-lookups.

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

    Weighted

    public static final int Weighted

    Constructor Detail

    KCompletion

    protected KCompletion(Class dummy)

    KCompletion

    public KCompletion()
    Constructor, nothing special here :)

    UNKNOWN: Constructor, nothing special here :)

    Method Detail

    addItem

    public void addItem(String item)
    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

    UNKNOWN: Adds an item to the list of available completions.

    addItem

    public void addItem(String item, int weight)
    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

    UNKNOWN: Adds an item to the list of available completions.

    allMatches

    public ArrayList 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: KCompletion

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

    allMatches

    public ArrayList allMatches(String string)
    Returns a list of all items matching string.

    Parameters: string the string to match

    Returns: the list of all matches

    UNKNOWN: Returns a list of all items matching string.

    className

    public String className()

    clear

    public void clear()
    Removes all inserted items.

    UNKNOWN: Removes all inserted items.

    completionMode

    public int completionMode()
    Return the current completion mode. May be different from KGlobalSettings.completionMode(), if you explicitly called setCompletionMode().

    Returns: the current completion mode

    See Also: KCompletion

    UNKNOWN: Return the current completion mode.

    dispose

    public void dispose()
    Delete the wrapped C++ instance ahead of finalize()

    finalize

    protected void finalize()
    Deletes the wrapped C++ instance

    hasMultipleMatches

    public boolean hasMultipleMatches()
    Returns true when more than one match is found.

    Returns: true if there are more than one match

    See Also: KCompletion

    UNKNOWN: Returns true when more than one match is found.

    ignoreCase

    public boolean ignoreCase()
    Return whether KCompletion acts case insensitively or not. Default is false (case sensitive).

    Returns: true if the case will be ignored

    See Also: KCompletion

    UNKNOWN: Return whether KCompletion acts case insensitively or not.

    insertItems

    public void insertItems(String[] items)
    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

    UNKNOWN: Inserts items into the list of possible completions.

    isDisposed

    public boolean isDisposed()
    Has the wrapped C++ instance been deleted?

    isEmpty

    public boolean isEmpty()
    Returns true when the completion object contains no entries.

    UNKNOWN: Returns true when the completion object contains no entries.

    isSoundsEnabled

    public boolean isSoundsEnabled()
    Tells you whether KCompletion will play sounds on certain occasions. Default is enabled.

    Returns: true if sounds are enabled

    See Also: KCompletion KCompletion

    UNKNOWN: Tells you whether KCompletion will play sounds on certain occasions.

    items

    public ArrayList items()
    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: KCompletion

    UNKNOWN: Returns a list of all items inserted into KCompletion.

    lastMatch

    public String lastMatch()
    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. null is returned when there is no last match.

    UNKNOWN: Returns the last match.

    makeCompletion

    public String makeCompletion(String string)
    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 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 null if there is no matching item.

    See Also: KCompletion KCompletion

    UNKNOWN: Attempts to find an item in the list of available completions, that begins with string.

    metaObject

    public QMetaObject metaObject()

    nextMatch

    public String 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, null is returned and a sound is issued

    See Also: KCompletion

    UNKNOWN: Returns the next item from the matching-items-list.

    order

    public int order()
    Returns the completion order.

    Returns: the current completion order.

    See Also: KCompletion

    UNKNOWN: Returns the completion order.

    postProcessMatch

    protected void postProcessMatch(StringBuffer match)
    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: KCompletion

    UNKNOWN: This method is called after a completion is found and before the matching string is emitted.

    postProcessMatches

    protected void postProcessMatches(String[] matches)
    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: KCompletion

    UNKNOWN: This method is called before a list of all available completions is emitted via #matches.

    previousMatch

    public String 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, null is returned and a sound is be issued.

    See Also: KCompletion

    UNKNOWN: Returns the next item from the matching-items-list.

    removeItem

    public void removeItem(String item)
    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

    UNKNOWN: Removes an item from the list of available completions.

    setCompletionMode

    public void setCompletionMode(int mode)
    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: KCompletion KGlobalSettings

    UNKNOWN: Sets the completion mode to Auto/Manual, Shell or None.

    setEnableSounds

    public void setEnableSounds(boolean enable)
    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: KCompletion

    UNKNOWN: Enables/disables playing a sound when

    setIgnoreCase

    public void setIgnoreCase(boolean ignoreCase)
    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: KCompletion

    UNKNOWN: Setting this to true makes KCompletion behave case insensitively.

    setItems

    public void setItems(String[] list)
    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: KCompletion

    UNKNOWN: Sets the list of items available for completion.

    setOrder

    public void setOrder(int order)
    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: KCompletion

    UNKNOWN: KCompletion offers three different ways in which it offers its items:

    slotMakeCompletion

    public void slotMakeCompletion(String string)
    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: KCompletion

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

    slotNextMatch

    public void slotNextMatch()
    Searches the next matching item and emits it via match(). Same as nextMatch() (just as a slot).

    See Also: KCompletion

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

    slotPreviousMatch

    public void slotPreviousMatch()
    Searches the previous matching item and emits it via match(). Same as previousMatch() (just as a slot).

    See Also: KCompletion

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

    substringCompletion

    public ArrayList substringCompletion(String string)
    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: KCompletion

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