functionCancellationAndObserver.h

/* ********************************************************************
    itom software
    URL: http://www.uni-stuttgart.de/ito
    Copyright (C) 2020, Institut fuer Technische Optik (ITO),
    Universitaet Stuttgart, Germany

    This file is part of itom and its software development toolkit (SDK).

    itom is free software; you can redistribute it and/or modify it
    under the terms of the GNU Library General Public Licence as published by
    the Free Software Foundation; either version 2 of the Licence, or (at
    your option) any later version.
   
    In addition, as a special exception, the Institut fuer Technische
    Optik (ITO) gives you certain additional rights.
    These rights are described in the ITO LGPL Exception version 1.0,
    which can be found in the file LGPL_EXCEPTION.txt in this package.

    itom 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 Licence for more details.

    You should have received a copy of the GNU Library General Public License
    along with itom. If not, see <http://www.gnu.org/licenses/>.
*********************************************************************** */

#ifndef FUNCCANCELLATIONANDOBSERVER_H
#define FUNCCANCELLATIONANDOBSERVER_H

#include "commonGlobal.h"
#include <qscopedpointer.h>
#include <qobject.h>



#if !defined(Q_MOC_RUN) || defined(ITOMCOMMONQT_MOC) //only moc this file in itomCommonQtLib but not in other libraries or executables linking against this itomCommonQtLib

namespace ito
{

class FunctionCancellationAndObserverPrivate; //forward declaration

class ITOMCOMMONQT_EXPORT FunctionCancellationAndObserver : public QObject
{
    Q_OBJECT
    
public:
    enum CancellationReason
    {
        ReasonGeneral = 1,
        ReasonKeyboardInterrupt = 2 //if the python script execution has been terminated
    };


    FunctionCancellationAndObserver(int progressMinimum = 0, int progressMaximum = 100, QObject *parent = NULL);

    /*
    \sa ItomSharedSemaphore::deleteSemaphore
    */
    virtual ~FunctionCancellationAndObserver();

    bool isCancelled() const;

    CancellationReason cancellationReason();

    int progressMinimum() const;

    int progressMaximum() const;

    /*
        This method emits the progressValueChanged signal. It can for instance be connected
        with a 'setValue' slot of a QProgressBar.

        The value will be clipped to progressMinimum and progressMaximum.
    */
    void setProgressValue(int value);

    int progressValue() const;

    /*
        This method emits the progressTextChanged signal. It can for instance be connected
        with a 'setText' slot of a QLabel.

        The text should inform about the step, the long-running method is currently executing.
    */
    void setProgressText(const QString &text);

    QString progressText();

Q_SIGNALS:
    void progressTextChanged(QString text);
    void progressValueChanged(int value);
    void cancellationRequested();
    void resetDone();

public Q_SLOTS:
    /*
    It is the responsibility of the called function itself to regulariy check the isCancelled() method
    and stop the function call as soon as possible.

    The reason ReasonKeyboardInterrupt should only be set by the method PythonEngine::pythonInterruptExecutionThreadSafe
    to avoid nested errors. In this case, itom.filter will not set an exception, since the keyboardInterrupt exception
    is automatically raised.

    Emits the cancellationRequested signal.
    */
    void requestCancellation(CancellationReason reason = CancellationReason::ReasonGeneral);

    /*
    Emits progressTextChanged and progressValueChanged with the new values and then the resetDone signal.
    */
    void reset();

private:
    Q_DISABLE_COPY(FunctionCancellationAndObserver)

    QScopedPointer<FunctionCancellationAndObserverPrivate> d_ptr; 
    Q_DECLARE_PRIVATE(FunctionCancellationAndObserver);
};

} //end namespace ito

#endif //#if !defined(Q_MOC_RUN) || defined(ITOMCOMMONQT_MOC)

#endif