kcompletion.h

Go to the documentation of this file.

/* This file is part of the KDE libraries
   Copyright (C) 1999,2000 Carsten Pfeiffer <pfeiffer@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/

#ifndef KCOMPLETION_H
#define KCOMPLETION_H

#include <kdeui_export.h>
#include <kglobalsettings.h>
#include <ksortablelist.h>
#include <kshortcut.h>

#include <QtCore/QMap>
#include <QtCore/QObject>
#include <QtCore/QString>
#include <QtCore/QStringList>
#include <QtCore/QPointer>

class KCompTreeNode;
class KCompletionPrivate;
class KCompletionBasePrivate;
class KCompletionMatchesWrapper;
class KCompletionMatches;

class KDEUI_EXPORT KCompletion : public QObject
{
    Q_ENUMS( CompOrder )
    Q_PROPERTY( CompOrder order READ order WRITE setOrder )
    Q_PROPERTY( bool ignoreCase READ ignoreCase WRITE setIgnoreCase )
    Q_PROPERTY( QStringList items READ items WRITE setItems )
    Q_OBJECT

public:
    enum CompOrder { Sorted,    
                     Insertion, 
                     Weighted   
    };

    KCompletion();

    virtual ~KCompletion();

    virtual QString makeCompletion( const QString& string );

    QStringList substringCompletion( const QString& string ) const;

    QString previousMatch();

    QString nextMatch();

    virtual const QString& lastMatch() const;

    QStringList items() const;

    bool isEmpty() 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 setSoundsEnabled( bool enable );

    bool soundsEnabled() const;

    bool hasMultipleMatches() const;

public Q_SLOTS:
    void slotMakeCompletion( const QString& string ) { //inline (redirect)
        (void) makeCompletion( string );
    }

    void slotPreviousMatch() { //inline (redirect)
        (void) previousMatch();
    }

    void slotNextMatch() { //inline (redirect)
        (void) nextMatch();
    }

    // FIXME ###: KDE4: unify the nomenclature.  We have insertItems, addItem,
    //            setItems...
    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();


Q_SIGNALS:
    void match( const QString& item);

    void matches( const QStringList& matchlist);

    void multipleMatches();

protected:
    virtual void postProcessMatch( QString *pMatch ) const;

    virtual void postProcessMatches( QStringList * pMatches ) const;

    virtual void postProcessMatches( KCompletionMatches * pMatches ) const;

private:
    void            addWeightedItem( const QString& );
    QString         findCompletion( const QString& string );
    void            findAllCompletions( const QString&,
                                        KCompletionMatchesWrapper *matches,
                                        bool& hasMultipleMatches ) const;

    void extractStringsFromNode( const KCompTreeNode *,
                                 const QString& beginning,
                                 KCompletionMatchesWrapper *matches,
                                 bool addWeight = false ) const;
    void extractStringsFromNodeCI( const KCompTreeNode *,
                                   const QString& beginning,
                                   const QString& restString,
                                   KCompletionMatchesWrapper *matches) const;

    enum        BeepMode { NoMatch, PartialMatch, Rotation };
    void        doBeep( BeepMode ) const;

private:
    Q_DISABLE_COPY( KCompletion )
    KCompletionPrivate* const d;
};

// some more helper stuff
typedef KSortableList<QString> KCompletionMatchesList;
class KCompletionMatchesPrivate;

class KDEUI_EXPORT KCompletionMatches : public KCompletionMatchesList
{
public:
    KCompletionMatches( bool sort );

    KCompletionMatches( const KCompletionMatches& );

    KCompletionMatches &operator=( const KCompletionMatches& );

    KCompletionMatches( const KCompletionMatchesWrapper& matches );

    ~KCompletionMatches();
    void removeDuplicates();
    QStringList list( bool sort = true ) const;
    bool sorting() const;

private:
    KCompletionMatchesPrivate * const d;
};

class KDEUI_EXPORT KCompletionBase
{
public:
    enum KeyBindingType {
        TextCompletion,
        PrevCompletionMatch,
        NextCompletionMatch,
        SubstringCompletion
    };


    // Map for the key binding types mentioned above.
    typedef QMap<KeyBindingType, KShortcut> KeyBindingMap;

    KCompletionBase();

    virtual ~KCompletionBase();

    KCompletion* completionObject( bool hsig = true );

    virtual void setCompletionObject( KCompletion* compObj, bool hsig = true );

    virtual void setHandleSignals( bool handle );

    bool isCompletionObjectAutoDeleted() const;

    void setAutoDeleteCompletionObject( bool autoDelete );

    void setEnableSignals( bool enable );

    bool handleSignals() const;

    bool emitSignals() const;

    virtual void setCompletionMode( KGlobalSettings::Completion mode );

    KGlobalSettings::Completion completionMode() const;

    bool setKeyBinding( KeyBindingType item , const KShortcut& key );

    KShortcut getKeyBinding( KeyBindingType item ) const;

    void useGlobalKeyBindings();

    virtual void setCompletedText( const QString& text ) = 0;

    virtual void setCompletedItems( const QStringList& items, bool autoSuggest =true ) = 0;

    KCompletion* compObj() const;

protected:
    KeyBindingMap getKeyBindings() const;

    void setDelegate( KCompletionBase *delegate );

    KCompletionBase *delegate() const;

private:
    // This method simply sets the autodelete boolean for
    // the completion object, the emit signals and handle
    // signals internally flags to the provided values.
    void setup( bool, bool, bool );

    // BCI
protected:
    virtual void virtual_hook( int id, void* data );
private:
    Q_DISABLE_COPY( KCompletionBase )
    KCompletionBasePrivate * const d;
};

#endif // KCOMPLETION_H