/***************************************************************************
 UndoTransactionGuard.h  -  guard class for undo transactions
                             -------------------
    begin                : Sat May 26, 2001
    copyright            : (C) 2001 by Thomas Eschenbacher
    email                : Thomas Eschenbacher <thomas.eschenbacher@gmx.de>

 ***************************************************************************/

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

#ifndef UNDO_TRANSACTION_GUARD_H
#define UNDO_TRANSACTION_GUARD_H

#include "config.h"

#include <QtGlobal>

class QString;

namespace Kwave {

    class SignalManager;
    class UndoAction;
    class Plugin;

    /**
     * @class UndoTransactionGuard
     * A simple guard class for opening and closing an undo transaction
     * operating on a SignalManager. Several nested UndoTransactionGuards
     * (or undo transactions) are allowed.
     */
    class Q_DECL_EXPORT UndoTransactionGuard
    {

    public:
        /**
         * Constructor. Also determines the name of the transaction if
         * it is the first of several nested transactions.
         * @param manager reference to the SignalManager we operate on
         * @param name the name of the transaction as a user-readable and
         *        localized string. [optional]
         */
        explicit UndoTransactionGuard(Kwave::SignalManager &manager,
                                      const QString &name = QString());

        /**
         * Constructor for use from a plugin. Also determines the name of the
         * transaction if it is the first of several nested transactions.
         * @param plugin reference to the plugin (you should pass
         *               <code>*this</code>.
         * @param name the name of the transaction as a user-readable and
         *        localized string. [optional] If you pass null or omit this
         *        parameter, the name of the plugin will be used instead.
         */
        explicit UndoTransactionGuard(Kwave::Plugin &plugin,
                                      const QString &name = QString());

        /** Destructor. */
        virtual ~UndoTransactionGuard();

        /**
         * Tries to free memory for a new undo action and stores all needed
         * data if successful.
         * @param action UndoAction to that is to be registered
         * @return true if the action is allowed, false if the user has
         *         chosen to abort the operation if the memory limit of
         *         the undo buffer would be exceeded. The return value
         *         will also be false if the action is null.
         * @note If undo is currently not enabled, the passed UndoAction
         *       will be ignored and not freed, the return value will
         *       be false. So it is safer not to call this function if
         *       undo is not enabled.
         */
        bool registerUndoAction(UndoAction *action);

        /**
         * Aborts the undo transaction, discards all undo data and restores
         * the previous "modified" state of the signal.
         */
        void abort();

    private:

        /** Reference to the responsible SignalManager */
        Kwave::SignalManager &m_manager;

        /** the initial "modified" state of the signal */
        bool m_initial_modified;

    };

}

#endif /* UNDO_TRANSACTION_GUARD_H */

//***************************************************************************
//***************************************************************************
