Some implementation and API change

2 files changed, 529 insertions, 21 deletions

diff --git a/libopie2/opieui/okeyconfigwidget.cpp b/libopie2/opieui/okeyconfigwidget.cpp
new file mode 100644
index 0000000..d52a55f
--- a/dev/null
+++ b/libopie2/opieui/okeyconfigwidget.cpp
@@ -0,0 +1,408 @@
+#include "okeyconfigwidget.h"
+
+
+
+
+using namespace Opie::Ui;
+
+
+/**
+ * The default Constructor of a OKeyPair.
+ * A Key and a Modifier ( Alt/Shift/Ctrl )
+ * needs to be supplied.
+ * Use Qt::Key for the information.
+ * The default arguments  create an Empty OKeyPair. If you
+ * want to get an empty OKeyPair use the static method for getting
+ * the emptyKey()
+ *
+ * @see OKeyPair OKeyPair::emptyKey()
+ */
+OKeyPair::OKeyPair( int key, int mod )
+    : m_key( key ), m_mod( mod )
+{}
+
+/**
+ * The destructor
+ */
+OKeyPair::~OKeyPair() {}
+
+
+/**
+ * Is this OKeyPair empty/valid?
+ */
+bool OKeyPair::isEmpty()const {
+    return ( ( m_key == -1 )&& ( m_mod == -1 ) );
+}
+
+/**
+ * get the keycode for this OKeyPair. The Key relates to Qt::Key.
+ *
+ * @see Qt::Key
+ * @see setKey
+ */
+int OKeyPair::keycode()const {
+    return m_key;
+}
+
+/**
+ * get the modifier key for this OKeyPair. The Modifier State relates
+ * to the Qt::Modifier
+ *
+ * @see Qt::Modifier
+ * @see setModifier
+ */
+int OKeyPair::modifier()const {
+    return m_mod;
+}
+
+
+/**
+ * Set the keycode
+ * @param key The Keycode to set
+ *
+ * @see keycode()
+ * @see Qt::Key
+ */
+void OKeyPair::setKeycode( int key ) {
+
+}
+
+/**
+ * Set the modifier key
+ *
+ * @param the Modifier key
+ * @see Qt::Modifier
+ * @see modifier()
+ */
+void OKeyPair::setModifier( int mod ) {
+
+}
+
+/**
+ * Return  an OKeyPair for the Return Key without any modifier.
+ */
+OKeyPair OKeyPair::returnKey() {
+    return OKeyPair( Qt::Key_Return, 0 );
+}
+
+/**
+ * Return an OKeyPair for the Left Arrow Key
+ * without any modifier Key
+ */
+OKeyPair OKeyPair::leftArrowKey() {
+    return OKeyPair( Qt::Key_Left, 0 );
+}
+
+/**
+ * Return an OKeyPair for the Right Arrow Key
+ * without any modifier Key
+ */
+OKeyPair OKeyPair::rightArrowKey() {
+    return OKeyPair( Qt::Key_Right, 0 );
+}
+
+/**
+ * Return an OKeyPair for the Up Arrow Key
+ * without any modifier Key
+ */
+OKeyPair OKeyPair::upArrowKey() {
+    return OKeyPair( Qt::Key_Up, 0 );
+}
+
+/**
+ * Return an OKeyPair for the Down Arrow Key
+ * without any modifier Key
+ */
+OKeyPair OKeyPair::downArrowKey() {
+    return OKeyPair( Qt::Key_Down, 0 );
+}
+
+/**
+ * Return an Empty OKeyPair
+ */
+OKeyPair OKeyPair::emptyKey() {
+    return OKeyPair;
+}
+
+/**
+ * This functions uses the Opie::Core::ODevice::buttons
+ * for OKeyPairList
+ *
+ * @see Opie::Core::ODevice
+ * @see Opie::Core::ODeviceButton
+ * @see Opie::Core::ODevice::button
+ */
+OKeyPairList OKeyPair::hardwareKeys() {
+    const QValueList<Opie::Core::ODeviceButton> but = Opie::Core::ODevice::inst()->buttons();
+    OKeyPairList lst;
+
+    for ( QValueList<Opie::Core::ODeviceButton>::Iterator it = but.begin();
+          it != but.end(); ++it )
+        lst.append( OKeyPair( (*it).keycode(), 0 ) );
+
+
+    return lst;
+}
+
+/**
+ * The normal Constructor  to create a OKeyConfigItem
+ *
+ * You can set the the key paramater of this item but if
+ * you use this item with the OKeyConfigManager your setting
+ * will be overwritten.
+ *
+ * @param text The text exposed to the user
+ * @param config_key The key used in the config
+ * @param pix A Pixmap associated  with this Item
+ * @param key The OKeyPair used
+ * @param def The OKeyPair used as default
+ *
+ */
+OKeyConfigItem::OKeyConfigItem( const QString& text, const QCString& config_key,
+                                const QPixmap& pix, int id, const OKeyPair& def,
+                                const OKeyPair& key)
+    : m_text( text ), m_config( config_key ), m_pix( pix ),
+      m_id( id ), m_def( def ), m_key( key ) {}
+
+/**
+ * A special Constructor for converting from an Opie::Core::ODeviceButton
+ * delivered by Opie::Core::ODevice::buttons()
+ * There is no Config Key set and both default key and key are set
+ * to Opie::Core::ODeviceButton::keycode() and 0 to modifier
+ *
+ * @see Opie::Core::ODevice
+ * @see Opie::Core::ODeviceButton
+ * @see Opie::Core::ODevice::buttons()
+ */
+OKeyConfigItem::OKeyConfigItem( Opie::Core::ODeviceButton& b )
+    : m_text( b.userText() ), m_pix( b.pixmap() ), m_id( -1 )
+      m_def( OKeyPair( b.keycode(), 0 ) ), m_key( OKeyPair( b.keycode(), 0 ) )
+{}
+
+
+/**
+ * Destructor
+ */
+OKeyConfigItem::~OKeyConfigItem() {}
+
+
+/**
+ * The text exposed to the user
+ *
+ * @see setText
+ */
+QString OKeyConfigItem::text()const {
+    return m_text;
+}
+
+/**
+ * The pixmap shown to the user for your action/key
+ *
+ * @see setPixmap
+ */
+QPixmap OKeyConfigItem::pixmap()const {
+    return m_pix;
+}
+
+/**
+ * Return the OKeyPair this OKeyConfigItem is configured for.
+ *
+ * @see setKeyPair
+ */
+OKeyPair OKeyConfigItem::keyPair()const {
+    return m_key;
+}
+
+/**
+ * Return the default OKeyPair
+ * @see setDefaultKeyPair
+ */
+OKeyPair OKeyConfigItem::defaultKeyPair()const {
+    return m_def;
+}
+
+
+/**
+ * Return the Id you assigned to this item.
+ * setting is only possible by the constructor
+ */
+int OKeyConfigItem::id()const{
+    return m_id;
+}
+
+/**
+ * reutrn the Config Key. Setting it is only possible
+ * by the constructor
+ */
+QCString OKeyConfigItem::configKey()const {
+    return m_config;
+}
+
+/**
+ * Set the text
+ *
+ * @param text Set the Text of this Action to text
+ * @see text()
+ */
+void OKeyConfigItem::setText( const QString& text ) {
+    m_text = text;
+}
+
+/**
+ * Set the pixmap of this action
+ *
+ * @param pix The Pixmap to set
+ * @see pixmap()
+ */
+void OKeyConfigItem::setPixmap( const QPixmap& pix ) {
+    m_pix = pix;
+}
+
+/**
+ * Set the KeyPair the OKeyConfigItem uses.
+ * Your set Key could get overwritten if you use
+ * the manager or GUI to configure the key
+ *
+ * @param key Set the OKeyPair used
+ * @see keyPair()
+ */
+void OKeyConfigItem::setKeyPair( const OKeyPair& key) {
+    m_key = key;
+}
+
+/**
+ * Set the default KeyPair.
+ *
+ * @param key The default keypair
+ * @see defaultKeyPair()
+ */
+void OKeyConfigItem::setDefaultKeyPair( const OKeyPair& key ) {
+    m_def = key;
+}
+
+/**
+ * @internal
+ */
+void OKeyConfigItem::setConfigKey( const QCString& str) {
+    m_config = str;
+    m_config.detach();
+}
+
+/**
+ * @internal
+ */
+void OKeyConfigItem::setId( int id ) {
+    m_id = id;
+}
+
+/**
+ * If the item is not configured isEmpty() will return true
+ * It is empty if no text is present and no default
+ * and no configured key
+ */
+bool OKeyConfigItem::isEmpty()const {
+    if ( !m_def.isEmpty()  ) return false;
+    if ( !m_key.isEmpty()  ) return false;
+    if ( !m_text.isEmpty() ) return false;
+
+    return true;
+}
+
+/**
+ * \brief c'tor
+ * The Constructor for a OKeyConfigManager
+ *
+ * You can use this manager in multiple ways. Either make it handle
+ * QKeyEvents
+ *
+ * \code
+ * Opie::Core::Config conf = oApp->config();
+ * Opie::Ui::OKeyPairList blackList;
+ * blackList.append(Opie::Ui::OKeyPair::leftArrowKey());
+ * blackList.append(Opie::Ui::OKeyPair::rightArrowKey());
+ * Opie::Ui::OKeyConfigManager *manager = new Opie::Ui::OKeyConfigManager(conf,"key_actions",blackList,
+ *                                                                        false);
+ * QListView *view = new QListView();
+ * manager->handleWidget(view);
+ * manager->addKeyConfig( Opie::Ui::OKeyPair::returnKey());
+ * manager->load();
+ *
+ * connect(manager,SIGNAL(actionActivated(QWidget*,QKeyEvent*,const Opie::Ui::OKeyConfigItem&)),
+ *         this,SLOT(slotHandleKey(QWidget*,QKeyEvent*,const Opie::Ui::OKeyConfigItem&)));
+ *
+ * ....
+ *
+ * void update(){
+ *  QDialog diag(true);
+ *  QHBoxLayout *lay = new QHBoxLayout(&diag);
+ *  Opie::Ui::OKeyConfigWidget *wid = new Opie::Ui::OKeyConfigWidget(manager,&diag);
+ *  wid->setChangeMode(Opie::Ui::OKeyConfigWidget::Queu);
+ *  lay->addWidget(wid);
+ *  if(QPEApplication::execDialog( &diag)== QDialog::Accept){
+ *        wid->save();
+ *  }
+ * }
+ *
+ * ....
+ * MyListView::keyPressEvent( QKeyEvent* e ){
+ *     Opie::Ui::OKeyConfigItem item = manager->handleKeyEvent(e);
+ *     if(!item.isEmpty() ){
+ *         switch(item.id()){
+ *           case My_Delete_Key:
+ *             break;
+ *         }
+ *     }
+ * }
+ *
+ * \endcode
+ *
+ * @param conf The Config where the KeySetting should be stored
+ * @param group The group where the KeySetting will be stored
+ * @param black Which keys shouldn't be allowed to handle
+ * @param grabkeyboard Calls QPEApplication::grabKeyboard to allow handling of DeviceButtons
+ * @param par The parent/owner of this manager
+ * @param name The name of this object
+ */
+OKeyConfigManager::OKeyConfigManager( Opie::Core::OConfig* conf,
+                                      const QString& group,
+                                      OKeyPairList black,
+                                      bool grabkeyboard, QObject* par,
+                                      const char* name)
+    : QObject( par, name ), m_conf( conf ), m_group( group ),
+      m_blackKeys( black ), m_grab( grabkeyboard )
+{}
+
+
+/**
+ * Destructor
+ */
+OKeyConfigWidget::~OKeyConfigWidget() {}
+
+/**
+ * Load the Configuration  from the OConfig
+ * If a Key is restricted but was in the config we will
+ * make the empty
+ * We will change the group of the OConfig Item!
+ */
+void OKeyConfigWidget::load() {
+    m_conf->setGroup( m_group );
+
+    /*
+     * Read each item
+     */
+    int key, mod;
+    for( OKeyConfigItemList::Iterator it = m_keys.begin();
+         it != m_keys.end(); ++it ) {
+        key = m_conf->readNumEntry( (*it).configKey()+"key", (*it).defaultKeyPair().keycode()  );
+        mod = m_conf->readNumEntry( (*it).configKey()+"mod", (*it).defaultKeyPair().modifier() );
+        (*it).setKeyPair( OKeyPair(key, mod) );
+    }
+}
+
+/**
+ * We will save the current configuration
+ * to the OConfig. We will change the group.
+ */
+void OKeyConfigWidget::save() {
+
+}
diff --git a/libopie2/opieui/okeyconfigwidget.h b/libopie2/opieui/okeyconfigwidget.h
index bcbb579..0d5d26f 100644
--- a/libopie2/opieui/okeyconfigwidget.h
+++ b/libopie2/opieui/okeyconfigwidget.h
@@ -1,8 +1,15 @@
+/*
+ * Copyright (C) 2004
+ * LGPL v2  zecke@handhelds.org
+ */
+
+
 #ifndef ODP_KEY_CONFIG_WIDGET_H
 #define ODP_KEY_CONFIG_WIDGET_H
 
 #include <opie2/oconfig.h>
+#include <opie2/odevice.h>
 
 #include <qstring.h>
 #include <qpixmap.h>
 #include <qbytearray.h>
@@ -13,52 +20,130 @@ class QKeyEvent;
 
 namespace Opie {
 namespace Ui {
 
+
+/**
+ * \brief small class representing a Key with possible modifiers
+ * This class holds information about key code and possible
+ * modifier state. That is the lowest level of the key input
+ * functions.
+ * There are also static methods to get special keys.
+ * OKeyPair will be used with \see OKeyConfigItem
+ *
+ * @since 1.2
+ */
+class OKeyPair {
+public:
+    typedef QValueList<OKeyPair> OKeyPairList;
+    OKeyPair( int key = -1, int modifier = -1);
+    ~OKeyPair();
+
+    bool operator==( const OKeyPair& );
+    bool operator!=( const OKeyPair& );
+
+    bool isEmpty()const;
+
+    int keycode()const;
+    int modifier()const;
+
+    void setKeycode( int );
+    void setModifier( int );
+
+    static OKeyPair returnKey();
+    static OKeyPair leftArrowKey();
+    static OKeyPair rightArrowKey();
+    static OKeyPair upArrowKey();
+    static OKeyPair downArrowKey();
+    static OKeyPair emptyKey();
+    static OKeyPairList hardwareKeys();
+
+private:
+    int m_key = -1;
+    int m_mod = -1;
+    class Private;
+    Private* d;
+};
+
+/**
+ * A class to represent an OKeyPair.
+ * It consists out of a Text exposed to the user, Config Key Item,
+ * Pixmap, A default OKeyPair and the set OKeyPair.
+ * You can also pass an id to it
+ *
+ * @since 1.1.2
+ */
 class OKeyConfigItem {
     friend class OKeyConfigManager;
 public:
     typedef QValueList<OKeyConfigItem> OKeyConfigItemList;
     OKeyConfigItem( const QString& text = QString::null , const QCString& config_key = QCString(),
                     const QPixmap& symbol  = QPixmap(),
-                    int key = 0, int mod = 0,
-                    int default_key = 0, int default_modified = 0 );
+                    int id = -1,
+                    const OKeyPair& set = OKeyPair::emptyKey(),
+                    const OKeyPair& def = OKeyPair::emptyKey() );
+    OKeyConfigItem( const Opie::Core::ODeviceButton& );
     ~OKeyConfigItem();
 
+    bool operator==( const OKeyConfigItem& );
+    bool operator!=( const OKeyConfigItem& );
+
     QString text()const;
     QPixmap pixmap()const;
-    int key()const;
-    int modifier()const;
-    int defaultKey()const;
-    int defaultModifier()const;
+    int id()const;
+
+    OKeyPair keyPair()const;
+    OKeyPair defaultKeyPair()const;
+    QCString configKey()const;
 
     void setText( const QString& text );
     void setPixmap( const QPixmap& );
-    void setKey( int );
-    void setModied( int );
-    void setDefaultKey( int );
-    void setDefaultModifier( int );
+    void setKeyPair( const OKeyPair& );
+    void setDefaultKeyPair( const OKeyPair& );
 
-    bool isConfigured()const;
     bool isEmpty()const;
+
+protected:
+    void setId( int id );
+    void setConfigKey( const QCString& );
+
 private:
+    int m_id;
     QString  m_text;
     QCString m_config;
     QPixmap  m_pix;
-    int      m_key;
-    int      m_mod;
-    int      m_defKey;
-    int      m_defMod;
+    OKeyPair m_key;
+    OKeyPair m_def;
     class Private;
     Private *d;
 };
 
 
-class OKeyConfig : public QObject {
+
+/**
+ * \brief A manager  to load and save Key Actions and get notified
+ * This is the Manager for KeyActions.
+ * You can say from which config and group to read data, to grab the
+ * keyboard to handle hardware keys, you can supply a blacklist of
+ * keys which should not be used by allowed to be used.
+ * You can even pass this manager to a Widget to do the configuration for you.
+ * You need to add OKeyConfigItem for your keys and then issue a load() to
+ * read the Key information.
+ * You can either handle the QKeyEvent yourself and ask this class if it is
+ * handled by your action and let give you the action. Or you can install
+ * the event filter and get a signal.
+ *
+ * @since 1.1.2
+ */
+class OKeyConfigManager : public QObject {
     Q_OBJECT
 public:
-    OKeyConfig(Opie::Core::OConfig *conf = 0,  bool grabkeyboard);
-    ~OKeyConfig();
+    OKeyConfigManager(Opie::Core::OConfig *conf = 0,
+                      const QString& group = QString::null,
+                      OKeyPairList &block = OKeyPairList(),
+                      bool grabkeyboard = false,  QObject *= 0,
+                      const char* name = 0      );
+    ~OKeyConfigManager();
 
     void load();
     void save();
 
@@ -67,16 +152,27 @@ public:
 
     void addKeyConfig( const OKeyConfigItem& );
     void removeKeyConfig( const OKeyConfigItem& );
 
+    void addBlackList( const OKeyPair& );
+    void removeBlackList( const OKeyPair& );
+    void clearBlackList();
+    OKeyPairList blackList()const;
+
     void handleWidget( QWidget* );
+
+    bool eventFilter( QObject*, QEvent* );
 signals:
-    void keyConfigChanged( OKeyConfig* );
-    void actionActivated( QWidget*, QKeyEvent*, const OKeyConfigItem& );
+    void keyConfigChanged( Opie::Ui::OKeyConfigManager* );
+    void actionActivated( QWidget*, QKeyEvent*, const Opie::Ui::OKeyConfigItem& );
 
 private:
+    OKeyPairList m_blackKeys;
     OKeyConfigItemList m_keys;
     QValueList<QWidget*> m_widgets;
+    Opie::Core::OConfig *m_conf;
+    QString m_group;
+    bool m_grab : 1;
     class Private;
     Private *d;
 };
 
@@ -85,16 +181,20 @@ class OKeyConfigWidget : public QHBox {
     Q_OBJECT
 public:
     enum ChangeMode { Imediate, Queu };
     OKeyConfigWidget( QWidget* parent = 0, const char* name = 0, WFlags fl = 0 );
-    OKeyConfigWidget( OKeyConfig *, QWidget* parent = 0, const char* = 0, WFlags = 0 );
+    OKeyConfigWidget( OKeyConfigManager *, QWidget* parent = 0, const char* = 0, WFlags = 0 );
     ~OKeyConfigWidget();
 
     void setChangeMode( enum ChangeMode );
     ChangeMode changeMode()const;
 
+    void setKeyConfig( OKeyConfigManager* );
+
     void reload();
+    void save();
 private:
+    OKeyConfigManager* m_manager;
     class Private;
     Private *d;
 };