1 files changed, 774 insertions, 0 deletions

diff --git a/libopie2/opieui/big-screen/omodalhelper.h b/libopie2/opieui/big-screen/omodalhelper.h
new file mode 100644
index 0000000..096cec4
--- a/dev/null
+++ b/libopie2/opieui/big-screen/omodalhelper.h
@@ -0,0 +1,774 @@
+/*
+               =.            This file is part of the OPIE Project
+             .=l.            Copyright (c)  2003 hOlgAr <zecke@handhelds.org>
+           .>+-=
+ _;:,     .>    :=|.         This library is free software; you can
+.> <`_,   >  .   <=          redistribute it and/or  modify it under
+:`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
+.="- .-=="i,     .._         License as published by the Free Software
+ - .   .-<_>     .<>         Foundation; either version 2 of the License,
+     ._= =}       :          or (at your option) any later version.
+    .%`+i>       _;_.
+    .i_,=:_.      -<s.       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., 59 Temple Place - Suite 330,
+                             Boston, MA 02111-1307, USA.
+ 
+*/
+
+#ifndef OMODALHELPER_H
+#define OMODALHELPER_H
+
+/* QT*/
+#include <qdialog.h>
+#include <qwidget.h>
+#include <qvaluelist.h>
+#include <qmap.h>
+#include <qvariant.h>
+
+typedef int TransactionID;
+
+class QDialog;
+
+namespace Opie
+{
+
+class OModalHelperControler;
+class OModalHelperSignal;
+
+struct OModalHelperBase
+{
+    virtual void done( int status, TransactionID ) = 0;
+    virtual void next( TransactionID ) = 0;
+    virtual void prev( TransactionID ) = 0;
+};
+
+/**
+ * Modality sucks! ;) But it is easy to work with
+ * do exec() on a dialog and you know everything is funky.
+ * You only need to have one Dialog loaded and so on.
+ * This class helps you to work like with modality and help
+ * you to keep things in sync
+ * It's a template class but it sends signals once one Item is ready
+ * the signals contains the status and id of the item and then you
+ * need fetch it.
+ * Handled Records will stay available until the first call to retrieve
+ * either the record via the TransactionID or via the QValueList<Record>. Note
+ * that most functions do not take handled records into account.
+ * Also if you edit an record external you can tell this class and it'll
+ * call the merge() function of your widget to maybe merge in these changes.
+ * It also supports multiple modes. Either it can create new dialogs
+ * for each item or it can queue them depending on your usage. But it is
+ * so smart that if only one item is shown that the queue bar is not shown
+ * See the example for simple usage.
+ *
+ * @short helps to life without modaility
+ * @author hOlgAr
+ * @version 0.01
+ */
+template<class Dialog, class Record, typename Id = int>
+class OModalHelper : private OModalHelperBase
+{
+    friend class OModalHelperSignal;
+    friend class OModalHelperControler;
+public:
+    typedef QValueList<Record> RecordList;
+    typedef QMap<Id, Record> IdMap;
+    typedef QMap<TransactionID, Id> TransactionMap;
+    typedef QMap<QDialog*, TransactionID> DialogMap
+    enum Mode { Queue, New };
+    OModalHelper(enum Mode mode, QObject* parnet );
+
+    bool handles( Id id)const;
+    TransactionID transactionID( Id id)const;
+
+    void suspend( bool = true );
+
+    void cancel();
+    void cancel( TransactionID );
+
+    void connectDone( QObject* rec, const char* slot );
+    void connectAccepted( QObject* rec, const char* slot );
+    void connectRejected( QObject* rec, const char* slot );
+
+    TransactionID handle( Id id, const Record& rec = Record() );
+
+    void edited( Id, int what, const QVariant& data );
+
+    Record record( TransactionID )const;
+    RecordList recordsDone()const;
+private:
+    virtual void done( int, TransactionID );
+    virtual void next( TransactionID );
+    virtual void prev( TransactionID );
+
+    Record nextRecord( TransactionID &, int & )const;
+    Record prevRecord( TransactionID &, int & )const;
+    int pos( TransactionID )const;
+    Dialog* newDialogRecord( const Record& );
+
+private:
+    OModalHelperDialog     *queuedDialog()const; // generate or recycle
+    OModalHelperDialog     *m_dialog;
+    OModalHelperSignal     *m_signal; // our signal
+    OModalHelperControler  *m_controler;
+    IdMap                  m_ids; // maps ids (uids) to a record
+    IdMap                  m_doneIds;
+    TransactionMap         m_transactions; // activate transactions
+    TransactionMap         m_done; // done and waiting for getting picked
+    DialogMap              m_editing; // only used for New Mode
+    enum Mode              m_mode; // the mode we're in
+bool                   m_disabled :1;
+};
+
+
+
+/* ### FIXME use namespace with Qt3 */
+
+/*
+ * A note on flow. The Signal is used for QT Signals when
+ * a record is done.
+ * There is either one controler and this controler slot will
+ * be connected to a dialog signal.
+ * In Queue we get the next and prev signals and call the Helper.
+ * this then changes the Record of the dialog and sets the transactionId
+ * of the controler.
+ * For the new mode
+ *
+ */
+
+class OModalHelperSignal : public QObject
+{
+    Q_OBJECT
+public:
+    OModalHelperSignal(OModalHelperBase* base,  QObject* parent);
+    ~OModalHelperSignal();
+
+signals:
+    done( int status,  TransactionID transaction );
+    accepted( TransactionID transaction );
+    rejected( TransactionID transaction );
+
+private:
+    OModalHelperBase* m_base;
+};
+
+
+class OModalHelperControler : public QObject
+{
+    Q_OBJECT
+public:
+    OModalHelperControler( OModalHelperBase* , QObject* parent);
+    virtual TransactionID transactionID()const;
+    void setTransactionID( TransactionID id );
+    QDialog* dialog()const;
+
+public slots:
+    virtual void done(int result );
+    virtual void next();
+    virtual void prev();
+private:
+    QDialog *m_dia;
+    TransactionID m_id;
+    OModalHelperBase *m_base;
+}
+
+struct OModalQueueBar;
+class OModalQueuedDialog : public QDialog
+{
+    Q_OBJECT
+public:
+    OModalQueuedDialog(QDialog *mainWidget);
+    ~OModalQueuedDialog();
+
+    QDialog* centerDialog()const;
+
+    void setQueueBarEnabled( bool = true );
+    void setRecord( int record, int count );
+
+signals:
+    void next();
+    void prev();
+
+private:
+    OModalQueueBar *m_bar;
+    QDialog *m_center;
+};
+
+
+/*
+ * Tcpp Template Implementation
+ */
+
+/**
+ * This is the simple Template c'tor. It takes the mode
+ * this helper should operate in and the parent object.
+ * This helper will be deleted when the parent gets deleted
+ * or you delete it yourself.
+ *
+ * @param mode The mode this dialog should be in
+ * @param parent The parent QObject of this helper.
+ */
+template<class Dialog, class Record, typename Id>
+OModalHelper<Dialog, Record, Id>::OModalHelper( enum Mode mode, QObject* parent )
+{
+    m_disabled = false;
+    m_mode = mode;
+    m_signal = new OModalHelperSignal( this, parent );
+    m_controler = new OModalHelperControler( this, m_signal );
+}
+
+
+/**
+ * This functions looks for your record and sees if it is
+ * handled with this helper. Note that done records
+ * will not be returned.
+ *
+ * @return true if the record is currenlty edited otherwise false
+ *
+ * @param Id The id which might be handled
+ */
+template<class Dialog, class Record, typename Id>
+bool OModalHelper<Dialog, Record, Id>::handles( Id id )const
+{
+    if ( m_transactions.isEmpty() )
+        return false;
+
+    TransactionMap::ConstIterator it = m_transactions.begin();
+    for ( ; it != m_transactions.end(); ++it )
+        if ( it.data() == id )
+            return true;
+
+    return false;
+}
+
+
+/**
+ * just like handles( Id ) but returns the TransactionId
+ */
+template<class Dialog, class Record, typename Id>
+TransactionID OModalHelper<Dialog, Record, Id>::transactionID( Id id)const
+{
+    if ( m_transactions.isEmpty() || !m_ids.contains( id ) )
+        return 0;
+
+    TransactionMap::ConstIterator it = m_transactions.begin();
+    for ( ; it != m_transactions.end(); ++it )
+        if ( it.data() == id )
+            return it.key();
+
+    return 0;
+}
+
+/**
+ * If you're requested to flush your data and you do not want
+ * to call cancel with this method you can disable and enabled
+ * all dialogs.
+ * The state gets saved so if you want to handle a new record the dialog
+ * will be disabled as well.
+ *
+ * @param sus If true setDisabled(TRUE) will be called otherwise FALSE
+ */
+template<class Dialog, class Record, typename Id>
+void OModalHelper<Dialog, Record, Id>::suspend(bool sus)
+{
+    m_disabled = sus;
+    if (m_mode == New )
+        for (DialogMap::Iterator it = m_editing.begin(); it != m_editing.end(); ++it )
+            it.key()->setDisabled( sus );
+    else if (m_dialog )
+        queuedDialog()->setDisabled( sus );
+}
+
+/**
+ * Cancel will cancel all current operations and clear the list
+ * of done operations as well.
+ * This also clears all done operations you did not popped
+ */
+template<class Dialog, class Record, typename Id>
+void OModalHelper<Dialog, Record, Id>::cancel()
+{
+    m_ids.clear();
+    m_doneIds.clear();
+    m_done.clear();
+    m_transactions.clear();
+
+    /* we also need to remove the QDialogs */
+    /* and hide the queue dialog if present */
+    if (m_mode == New && !m_editing.isEmpty() )
+    {
+        for (DialogMap::Iterator it = m_editing.begin(); it != m_editing.end(); ++it )
+            delete it.key();
+
+        m_editing.clear();
+    }
+    else if (m_dialog )
+        queuedDialog()->setRecord( 0, 0 );
+
+    m_controler->setTransactionID( 0 );
+}
+
+
+/**
+ * This cancels editing of the record behind the Transaction Number
+ * Note that if editing is already done it will also be removed from this list
+ */
+template<class Dialog, class Record, typename Id>
+void OModalHelper::cancel( TransactionID tid )
+{
+    /* wrong tid */
+    if (!m_transactions.contains( tid ) && !m_done.contains( tid) )
+        return;
+
+    if (m_mode == New )
+        /* reverse map eek */
+        for (DialogMap::Iterator it = m_editing.begin(); it != m_editing.end(); ++it )
+            if ( it.data() == tid )
+            {
+                it.key()->hide();
+                delete it.key();
+                it = m_editing.remove( it );
+                break;
+            }
+
+    /* now remove from the various maps  done and currently editing map*/
+    if (m_transactions.contains( tid ) )
+        m_ids.remove( m_transactions[tid]  );
+    if (m_done.contains( tid ) )
+        m_doneIds.remove( m_done[tid ]  );
+    m_done.remove( tid );
+    m_transactions.remove( tid );
+
+    next( 0 );
+}
+
+/**
+ * Connect to the done Signal. SIGNAL( done(int, TransactionID ) )
+ * This signal gets emitted whenever a Record was accepted or rejected
+ *
+ * @param rec  The object where the slot belongs to
+ * @param slot The slot which should be called. See the needed parameter above
+ */
+template<class Dialog, class Record, typename Id>
+void OModalHelper<Dialog, Record, Id>::connectDone( QObject* rec, const char* slot )
+{
+    QObject::connect(m_signal, SIGNAL(done(int, TransactionID) ),
+                     rec, slot );
+}
+
+/**
+ * Connect to the accepted Signal. SIGNAL( accepted(TransactionID ) )
+ * This signal gets emitted whenever a Record was accepted
+ *
+ * @param rec  The object where the slot belongs to
+ * @param slot The slot which should be called. See the needed parameter above
+ */
+template<class Dialog, class Record, typename Id>
+void OModalHelper<Dialog, Record, Id>::connectAccepted( QObject* rec, const char* slot )
+{
+    QObject::connect(m_signal, SIGNAL(accepted(TransactionID) ),
+                     rec, slot );
+}
+
+/**
+ * Same as the accepted method but this one gets emitted if the dialog
+ * got rejected.
+ * SIGNAL( rejected(TransactionID) )
+ *
+ * @param rec The QObject of the slot
+ * @param slot The slot make sure the signature is correct
+ */
+template<class Dialog, class Record, typename Id>
+void OModalHelper<Dialog, Record, Id>::connectRejected( QObject* rec, const char* slot )
+{
+    QObject::connect(m_signal, SIGNAL(rejected(TransactionID) ),
+                     rec, slot );
+}
+
+/**
+ * Tell the helper to handle a record. If the record is currently handled
+ * it will be made active.
+ * Already handled record which are waiting getting popped are not taken into account
+ * Otherwise this helpers make the record editable.
+ * The record supplied needs to have a valid copy operator and constructor.
+ * In the case where the record is already present the parameter gets discarded.
+ * If you want the new record to be taken you need to cancel the Transaction first
+ *
+ * @param id  The Identification of the Record. For PIM it would uid()
+ * @param rec The record we want to be edited
+ *
+ * @returns This functions returns the TransactionId assigned to the record
+ *
+ */
+template<class Dialog, class Record, typename Id>
+TransactionID OModalHelper<Dialog, Record, Id>::handle( Id id, const Record& rec )
+{
+    static TransactionID t_id = 0;
+    /*
+     *this method consists out of two parts divided each into New and Queued Mode.
+     * Either we have the dialog already, in this case we need to highlight the widget
+     * Or we need to add it.
+     */
+    TransactionID tid = 0;
+    /* we already have the record lets see if it was done or not */
+    if ( !(tid = transactionID( id ) ) )
+    {
+        if (m_mode == New )
+        {
+            /* lets find the dialog and show it need to reverse map*/
+            for (DialogMap::Iterator it = m_editing.begin(); it != m_editing.end(); ++it )
+                if ( it.data() == tid )
+                    it.key()->show();
+        }
+        else if (m_controler->transactionID() != tid )
+        {
+            int po = pos( tid );
+            m_controler->setTransactionID( tid );
+            static_cast<Dialog*>( queuedDialog()->centerDialog() )->setRecord( m_ids[ m_transactions[tid] ] );
+            queuedDialog()->setRecord( po, m_transactions.count() );
+        }
+    }
+    else
+    {
+        tid = ++t_id;
+        m_transactions.insert( tid, id );
+        m_ids.insert( id, rec );
+
+        if (m_mode == New )
+            m_editing.insert( newDialogRecord( rec ), tid );
+        else
+        {
+            m_controler->setTransactionID( tid );
+            static_cast<Dialog*>( queuedDialog()->centerDialog() )->setRecord( rec );
+            queuedDialog()->setRecord( m_transactions.count(), m_transactions.count() );
+        }
+    }
+    return tid;
+}
+
+/**
+ * The goal of this helper is to help you to create non blocking
+ * GUIs. In the example of the todolist you can have the edit dialog
+ * but still change the priority or completion inline even if you currently
+ * edit the record.
+ * Your Dialog needs to have a Method setData(int,const QVariant& ) which will be called
+ * in these cases.
+ * If you edit anything while a record is edited call this function to merge the
+ * change in. Note if the record is not handled here we will ignore the request
+ *
+ */
+template<class Dialog, class Record, typename Id>
+void OModalHelper<Dialog, Record, Id>::edited( Id id, int what, const QVariant& data )
+{
+    int tid;
+    if (!( tid = transactionID( id ) ) )
+        return;
+
+    if (m_mode == New )
+    {
+        for (DialogMap::Iterator it= m_editing.begin(); it != m_editing.end(); ++it )
+            if ( it.data() == tid )
+                it.key()->setData( what, data );
+    }
+    else
+    {
+        int po = pos( tid );
+        Dialog* dia = static_cast<Dialog*>( queuedDialog()->centerDialog() );
+        dia->setRecord( m_ids[id] );
+        dia->setData( what, data );
+        queuedDialog()->setRecord( pos, m_transactions.count() );
+    }
+}
+
+/**
+ * This functions either returns the unedited record the done record
+ * or a new empty Record using Record().
+ * If a done record is retrieved all traces are removed inside this class. This
+ * is what was called popping a  record. This means when you call this function
+ * with the same TransactionID an Empty record is retrieved.
+ *
+ */
+template<class Dialog, class Record, typename Id>
+Record OModalHelper<Dialog, Record, Id>::record( TransactionID tid)const
+{
+    if (m_transactions.contains( tid ) )
+        return m_ids[ m_transactions[tid] ];
+    else if (m_done.contains( tid ) )
+    {
+        Record rec = m_doneIds[ m_done[ tid] ];
+        m_doneIds.remove( m_done[ tid ] );
+        m_done.remove( tid );
+        return rec;
+    }
+    else
+        return Record();
+}
+
+/**
+ * Returns all done Records and removes all references to them internally. A 2nd call to this will
+ * only contain done record that where edited past the point
+ */
+template<class Dialog, class Record, typename Id>
+OModalHelper<Dialog,Record,Id>::RecordList OModalHelper<Dialog, Record, Id>::recordsDone()const
+{
+    RecordList list;
+
+    for (IdMap::ConstIterator it = m_doneIds.begin(); it != m_doneIds.end(); ++it )
+        list.append( it.data() );
+
+    /* clean up */
+    m_done.clear();
+    m_doneIds.clear();
+
+    return list;
+}
+
+
+/**
+ * @internal
+ */
+template<class Dialog, class Record, typename Id>
+void OModalHelper<Dialog, Record, Id>::done( int status, TransactionID tid)
+{
+    /* If we're in New mode the transaction Id does not count */
+    Record rec;
+
+    if (m_mode == New )
+    {
+        Dialog *dia = static_cast<Dialog*>( m_controler->dialog() );
+        m_controler->setTransactionID( 0 ); // set the internal dialog to 0l again
+        tid = m_editing[ dia ];
+        m_editing.remove( dia );
+        rec = dia->record();
+        delete dia;
+    }
+    else
+        rec = queuedDialog()->record();
+
+    Id id = m_transactions[ tid ];
+    if (result == QDialog::Accept )
+    {
+        m_doneIds.insert( is, rec  );
+        m_done.insert( tid, id );
+    }
+
+    m_transactions.remove( tid );
+    m_ids.remove( id );
+
+
+    if (status == QDialog::Accept )
+        emit m_signal->accepted( tid );
+    else
+        emit m_signal->rejected( tid );
+
+    emit m_signal->done( result, tid );
+
+    next( 0 );
+}
+
+/**
+ * @internal
+ */
+template<class Dialog, class Record, typename Id>
+void OModalHelper<Dialog, Record, Id>::next( TransactionID tid)
+{
+    if (m_mode == New )
+        return;
+
+    if (! (m_transactions.count() ) )
+    {
+        m_controler->setTransactionID( 0 );
+        queuedDialog()->setRecord( 0, 0 );
+        return;
+    }
+
+    int next;
+    Record rec;
+
+    /* save the maybe edited record before switching */
+    Dialog *dia = static_cast<Dialog*>( queuedDialog()->centerDialog() );
+    rec = dia->record();
+    m_ids.replace( m_transactions[tid], rec );
+
+    rec = nextRecord( tid, next );
+    queuedDialog()->setRecord( next, m_transactions.count() );
+    dia->setRecord( rec );
+
+    m_controler->setTransactionID( tid ); // was changed during the next call
+}
+
+/**
+ * @internal
+ */
+/*
+ * code duplication should create a template fcuntion
+ * which takes a pointer to a function ( next, prev ) function
+ */
+template<class Dialog, class Record, typename Id>
+void OModalHelper<Dialog, Record, Id>::prev( TransactionID tid )
+{
+    if (m_mode == New )
+        return;
+
+    if (! (m_transactions.count()) )
+    {
+        m_controler->setTransactionID( 0 );
+        queuedDialog()->setRecord( 0, 0 );
+        return;
+    }
+
+    int prev;
+    Record rec;
+
+    /* save the maybe edited record before switching */
+    Dialog *dia = static_cast<Dialog*>( queuedDialog()->centerDialog() );
+    rec = dia->record();
+    m_ids.replace( m_transactions[tid], rec );
+
+    rec = prevRecord( tid, prev );
+    queuedDialog()->setRecord( prev, m_transactions.count() );
+    dia->setRecord( rec );
+
+    m_controler->setTransactionID( tid ); // was changed during the next call
+}
+
+/**
+ * @internal
+ */
+template<class Dialog, class Record, typename Id>
+Record  OModalHelper<Dialog, Record, Id>::nextRecord( TransactionID &tid, int &po )
+{
+    /* if tid is == 0 we will take the first one */
+    /* pos starts at 1 here */
+    /* we know we're only called if there are records */
+    Record rec;
+    TransactionMap::Iterator it;
+    if (!tid )
+    {
+        po = 1;
+        TransactionMap::Iterator it = m_transactions.begin();
+    }
+    else
+    {
+        po = pos( tid );
+        /* if it is the last take the first as next */
+        if ( po == m_transactions.count() )
+        {
+            po = 1;
+            it = m_transactions.begin();
+        }
+        else
+        {
+            /* we know we're not the last and there is one after us */
+            it = m_transactions.find( tid );
+            ++it; ++po;
+        }
+    }
+
+    tid = it.key();
+    rec = m_ids[ tid ];
+    return rec;
+}
+
+/**
+ * @internal
+ */
+template<class Dialog, class Record, typename Id>
+Record OModalHelper<Dialog, Record, Id>::prevRecord( TransactionID& tid, int& pos )
+{
+    /* if tid is == 0 we will take the first one */
+    /* pos starts at 1 here */
+    /* we know we're only called if there are records */
+    Record rec;
+    TransactionMap::Iterator it;
+    if (!tid )
+    {
+        po = 1;
+        TransactionMap::Iterator it = m_transactions.begin();
+    }
+    else
+    {
+        po = pos( tid );
+        /* if it is the last take the first as next */
+        if ( po == 1 )
+        {
+            po = m_transactions.count();
+            it = m_transactions.end();
+            --it;
+        }
+        else
+        {
+            /* we know we're not the first and there is one before us */
+            it = m_transactions.find( tid );
+            --it; --po;
+        }
+    }
+
+    tid = it.key();
+    rec = m_ids[ tid ];
+    return rec;
+}
+
+/**
+ * @internal
+ */
+template<class Dialog, class Record, typename Id>
+int OModalHelper<Dialog, Record, Id>::pos( TransactionID id)const
+{
+    int i = 1;
+    for ( TransactionMap::ConstIterator it = m_transactions.begin(); it != m_transactions.end(); ++it, i++ )
+        if ( it.key() == id )
+            return i;
+
+
+    return 0;
+}
+
+/**
+ * @internal
+ */
+template<class Dialog, class Record, typename Id>
+Dialog* OModalHelper<Dialog, Record, Id>::newDialogRecord( const Record& rec )
+{
+    Dialog* dia = new Dialog;
+    dia->setRecord( rec );
+    dia->setDisabled( m_disabled );
+
+    QObject::connect(dia, SIGNAL(done(int) ),
+                     m_controler, SLOT(done(int) ) );
+
+    /* FIXME big screen QPEApplication needs fixed*/
+    dia->show();
+}
+
+template<class Record, class Dialog, typename Id>
+OModalHelperDialog* OModalHelper<Record, Dialog, Id>::queuedDialog()const
+{
+    if (!m_dialog )
+    {
+        m_dialog = new OModalHelperDialog;
+        m_dialog->setEnabled( m_disabled );
+
+        QObject::connect(m_dialog, SIGNAL(done(int) ),
+                         m_controler, SLOT(done(int) ) );
+        QObject::connect(m_dialog, SIGNAL(next() ),
+                         m_controler, SLOT(next() ) );
+        QObject::connect(m_dialog, SIGNAL(prev() ),
+                         m_controler, SLOT(prev() ) );
+    }
+    return m_dialog;
+}
+
+};
+
+#endif