kdecore Library API Documentation

kcompletion.h

00001 /* This file is part of the KDE libraries
00002    Copyright (C) 1999,2000 Carsten Pfeiffer <pfeiffer@kde.org>
00003 
00004    This library is free software; you can redistribute it and/or
00005    modify it under the terms of the GNU Library General Public
00006    License as published by the Free Software Foundation; either
00007    version 2 of the License, or (at your option) any later version.
00008 
00009    This library is distributed in the hope that it will be useful,
00010    but WITHOUT ANY WARRANTY; without even the implied warranty of
00011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012    Library General Public License for more details.
00013 
00014    You should have received a copy of the GNU Library General Public License
00015    along with this library; see the file COPYING.LIB.  If not, write to
00016    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00017    Boston, MA 02111-1307, USA.
00018 */
00019 
00020 #ifndef KCOMPLETION_H
00021 #define KCOMPLETION_H
00022 
00023 #include <qmap.h>
00024 #include <qptrlist.h>
00025 #include <qobject.h>
00026 #include <qstring.h>
00027 #include <qstringlist.h>
00028 #include <qguardedptr.h>
00029 
00030 #include "kdemacros.h"
00031 #include <kglobalsettings.h>
00032 #include <ksortablevaluelist.h>
00033 #include <kshortcut.h>
00034 
00035 class KCompTreeNode;
00036 class KCompletionPrivate;
00037 class KCompletionBasePrivate;
00038 class KCompletionMatchesWrapper;
00039 class KCompletionMatches;
00040 class QPopupMenu;
00041 
00133 class KCompletion : public QObject
00134 {
00135     Q_ENUMS( CompOrder )
00136     Q_PROPERTY( CompOrder order READ order WRITE setOrder )
00137     Q_PROPERTY( bool ignoreCase READ ignoreCase WRITE setIgnoreCase )
00138     Q_PROPERTY( QStringList items READ items WRITE setItems )
00139     Q_OBJECT
00140 
00141 public:
00146     enum CompOrder { Sorted,    
00147                      Insertion, 
00148                      Weighted   
00149     };
00150 
00154     KCompletion();
00155 
00156     // FIXME: copy constructor, assignment operator...
00157 
00161     virtual ~KCompletion();
00162 
00185     virtual QString makeCompletion( const QString& string );
00186 
00195     QStringList substringCompletion( const QString& string ) const;
00196 
00206     QString previousMatch();
00207 
00217     QString nextMatch();
00218 
00225     virtual const QString& lastMatch() const { return myLastMatch; }
00226 
00245     QStringList items() const;
00246     
00250     bool isEmpty() const;
00251 
00261     virtual void setCompletionMode( KGlobalSettings::Completion mode );
00262 
00270     KGlobalSettings::Completion completionMode() const {
00271         return myCompletionMode;
00272     }
00273 
00294     virtual void setOrder( CompOrder order );
00295 
00301     CompOrder order() const { return myOrder; }
00302 
00310     virtual void setIgnoreCase( bool ignoreCase );
00311 
00318     bool ignoreCase() const { return myIgnoreCase; }
00319 
00326     QStringList allMatches();
00327 
00333     QStringList allMatches( const QString& string );
00334 
00347     KCompletionMatches allWeightedMatches();
00348 
00354     KCompletionMatches allWeightedMatches( const QString& string );
00355 
00369     virtual void setEnableSounds( bool enable ) { myBeep = enable; }
00370 
00378     bool isSoundsEnabled() const { return myBeep; }
00379 
00385     bool hasMultipleMatches() const { return myHasMultipleMatches; }
00386 
00387 #ifndef KDE_NO_COMPAT
00388 
00392     void enableSounds() { myBeep = true; }
00393 
00398     void disableSounds() { myBeep = false; }
00399 #endif
00400     
00401 public slots:
00408     void slotMakeCompletion( const QString& string ) {
00409         (void) makeCompletion( string );
00410     }
00411 
00417     void slotPreviousMatch() {
00418         (void) previousMatch();
00419     }
00420 
00426     void slotNextMatch() {
00427         (void) nextMatch();
00428     }
00429 
00430     // FIXME ###: KDE4: unify the nomenclature.  We have insertItems, addItem,
00431     //            setItems...
00437     void insertItems( const QStringList& items );
00438 
00454     virtual void setItems( const QStringList& list);
00455 
00462     void addItem( const QString& item);
00463 
00475     void addItem( const QString& item, uint weight );
00476 
00483     void removeItem( const QString& item);
00484 
00488     virtual void clear();
00489 
00490 
00491 signals:
00498     void match( const QString& item);
00499 
00506     void matches( const QStringList& matchlist);
00507 
00513     void multipleMatches();
00514 
00515 protected:
00529     virtual void postProcessMatch( QString *match ) const { Q_UNUSED(match) }
00530 
00541     virtual void postProcessMatches( QStringList * matches ) const { Q_UNUSED(matches)}
00542 
00553     virtual void postProcessMatches( KCompletionMatches * matches ) const {Q_UNUSED(matches)}
00554 
00555 private:
00556     void            addWeightedItem( const QString& );
00557     QString         findCompletion( const QString& string );
00558     void            findAllCompletions( const QString&,
00559                                         KCompletionMatchesWrapper *matches,
00560                                         bool& hasMultipleMatches ) const;
00561 
00562     void extractStringsFromNode( const KCompTreeNode *,
00563                                  const QString& beginning,
00564                                  KCompletionMatchesWrapper *matches,
00565                                  bool addWeight = false ) const;
00566     void extractStringsFromNodeCI( const KCompTreeNode *,
00567                                    const QString& beginning,
00568                                    const QString& restString,
00569                                    KCompletionMatchesWrapper *matches) const;
00570 
00571     enum        BeepMode { NoMatch, PartialMatch, Rotation };
00572     void        doBeep( BeepMode ) const;
00573 
00574     KGlobalSettings::Completion myCompletionMode;
00575 
00576     CompOrder       myOrder;
00577     QString         myLastString;
00578     QString         myLastMatch;
00579     QString         myCurrentMatch;
00580     KCompTreeNode * myTreeRoot;
00581     QStringList     myRotations;
00582     bool            myBeep;
00583     bool            myIgnoreCase;
00584     bool            myHasMultipleMatches;
00585     uint            myRotationIndex;
00586 
00587 
00588 protected:
00589     virtual void virtual_hook( int id, void* data );
00590 private:
00591     KCompletionPrivate *d;
00592 };
00593 
00594 // some more helper stuff
00595 typedef KSortableValueList<QString> KCompletionMatchesList;
00596 class KCompletionMatchesPrivate;
00597 
00616 class KCompletionMatches : public KCompletionMatchesList
00617 {
00618 public:
00619     KCompletionMatches( bool sort );
00623     KCompletionMatches( const KCompletionMatchesWrapper& matches );
00624     ~KCompletionMatches();
00629     void removeDuplicates();
00636     QStringList list( bool sort = true ) const;
00642     bool sorting() const {
00643         return _sorting;
00644     }
00645 private:
00646     bool _sorting;
00647     KCompletionMatchesPrivate* d;
00648 };
00649 
00664 class KCompletionBase
00665 {
00666 public:
00672     enum KeyBindingType {
00676         TextCompletion,
00680         PrevCompletionMatch,
00684         NextCompletionMatch,
00688         SubstringCompletion
00689     };
00690 
00691 
00692     // Map for the key binding types mentioned above.
00693     typedef QMap<KeyBindingType, KShortcut> KeyBindingMap;
00694 
00698     KCompletionBase();
00699 
00703     virtual ~KCompletionBase();
00704     
00720     KCompletion* completionObject( bool hsig = true );
00721     
00738     virtual void setCompletionObject( KCompletion* compObj, bool hsig = true );
00739 
00752     virtual void setHandleSignals( bool handle );
00753 
00764     bool isCompletionObjectAutoDeleted() const {
00765         return m_delegate ? m_delegate->isCompletionObjectAutoDeleted() : m_bAutoDelCompObj;
00766     }
00767 
00777     void setAutoDeleteCompletionObject( bool autoDelete ) {
00778         if ( m_delegate )
00779             m_delegate->setAutoDeleteCompletionObject( autoDelete );
00780         else
00781             m_bAutoDelCompObj = autoDelete;
00782     }
00783 
00804     void setEnableSignals( bool enable ) {
00805         if ( m_delegate )
00806             m_delegate->setEnableSignals( enable );
00807         else
00808             m_bEmitSignals = enable;
00809     }
00810 
00816     bool handleSignals() const { return m_delegate ? m_delegate->handleSignals() : m_bHandleSignals; }
00817 
00823     bool emitSignals() const { return m_delegate ? m_delegate->emitSignals() : m_bEmitSignals; }
00824 
00845     virtual void setCompletionMode( KGlobalSettings::Completion mode );
00846 
00855     KGlobalSettings::Completion completionMode() const {
00856         return m_delegate ? m_delegate->completionMode() : m_iCompletionMode;
00857     }
00858 
00889     bool setKeyBinding( KeyBindingType item , const KShortcut& key );
00890 
00903     const KShortcut& getKeyBinding( KeyBindingType item ) const {
00904         return m_delegate ? m_delegate->getKeyBinding( item ) : m_keyMap[ item ];
00905     }
00906 
00918     void useGlobalKeyBindings();
00919 
00934     virtual void setCompletedText( const QString& text ) = 0;
00935 
00941     virtual void setCompletedItems( const QStringList& items ) = 0;
00942 
00954     KCompletion* compObj() const { return m_delegate ? m_delegate->compObj() : (KCompletion*) m_pCompObj; }
00955 
00956 protected:
00965     KeyBindingMap getKeyBindings() const { return m_delegate ? m_delegate->getKeyBindings() : m_keyMap; }
00966 
00972     void setDelegate( KCompletionBase *delegate );
00973 
00979     KCompletionBase *delegate() const { return m_delegate; }
00980 
00981 private:
00982     // This method simply sets the autodelete boolean for
00983     // the completion object, the emit signals and handle
00984     // signals internally flags to the provided values.
00985     void setup( bool, bool, bool );
00986 
00987     // Flag that determined whether the completion object
00988     // should be deleted when this object is destroyed.
00989     bool m_bAutoDelCompObj;
00990     // Determines whether this widget handles completion signals
00991     // internally or not
00992     bool m_bHandleSignals;
00993     // Determines whether this widget fires rotation signals
00994     bool m_bEmitSignals;
00995     // Stores the completion mode locally.
00996     KGlobalSettings::Completion m_iCompletionMode;
00997     // Pointer to Completion object.
00998     QGuardedPtr<KCompletion> m_pCompObj;
00999     // Keybindings
01000     KeyBindingMap m_keyMap;
01001     // we may act as a proxy to another KCompletionBase object
01002     KCompletionBase *m_delegate;
01003 
01004     // BCI
01005 protected:
01006     virtual void virtual_hook( int id, void* data );
01007 private:
01008     KCompletionBasePrivate *d;
01009 };
01010 
01011 #endif // KCOMPLETION_H
KDE Logo
This file is part of the documentation for kdecore Library Version 3.3.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Fri Jul 22 10:16:16 2005 by doxygen 1.3.6 written by Dimitri van Heesch, © 1997-2003