path: root/libopie2/opieui/big-screen/omodalhelper.h

/*
               =.            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