#include <KoProgressUpdater.h>

Inheritance diagram for KoProgressUpdater:

Public Types
enum	Mode { Threaded , Unthreaded }

Public Slots
void	cancel ()

Signals
void	triggerUpdateAsynchronously ()

Public Member Functions
bool	autoNestNames () const

void	clearState ()

bool	interrupted () const

	KoProgressUpdater (KoProgressProxy *progressProxy, Mode mode=Threaded)

	KoProgressUpdater (QPointer< KoUpdater > updater)
	a special constructor for connecting the progress updater to a self-destructible KoUpdater object.

	Private (KoProgressUpdater _q, KoProgressProxy proxy, QPointer< KoUpdater > parentUpdater, Mode _mode)

KoProgressProxy *	progressProxy ()

void	removePersistentSubtask (QPointer< KoUpdater > updater)

void	setAutoNestNames (bool value)

void	setUpdateInterval (int ms)

void	start (int range=100, const QString &text="")

QPointer< KoUpdater >	startSubtask (int weight=1, const QString &name=QString(), bool isPersistent=false)

int	updateInterval () const

void	updateParentText ()

	~KoProgressUpdater () override
	destructor

Public Attributes
bool	autoNestNames = false

bool	canceled

int	currentProgress = 0

bool	isStarted = false

bool	isUndefinedState = false

Mode	mode

QMutex	mutex

KoProgressUpdater *	q

QList< QPointer< KoUpdaterPrivate > >	subtasks

int	taskMax = 99

QString	taskName

KisSignalCompressor *	updateCompressor

int	updateInterval = 250

Private Slots
void	update ()

void	updateUi ()

Private Attributes
Private *const	d

KoProgressProxy *	parentProgressProxy

QPointer< KoUpdater >	parentUpdater

Private Attributes inherited from Private
KisCanvas2 *	canvas

int	displayedFrame

int	intendedFrame

Additional Inherited Members
Private Member Functions inherited from Private
	Private (KisCanvas2 *c)

Detailed Description

Allow multiple subtasks to safely update and report progress. This class is able to update a progress bar with the total progress of a project that may be separated into different subtasks. Each subtask will use one KoUpdater which that subtask can then report progress to. Each KoUpdater.setProgress() call will automatically calculate the total progress over the whole tasks made and update the progress bar with the total progress so far.

This class is created specifically with threading in mind so that subtasks can report their progress from their personal subthread and the progress bar will be updated correctly and not more often than repaints can occur.

Typical usage can be:

KoProgressUpdater *pu = new KoProgressUpdater(myProgressBar);
pu->start(100);
// create the subtasks
KoUpdater smooth = pu->startSubtask(5);
KoUpdater scale = pu->startSubtask(5);
KoUpdater cleanup = pu->startSubtask(1);

Doing a smooth.setProgress(50) will move the progress bar to 50% of the share of task 'smooth' which is 5 / 11 of the total and thus to 22.

KoProgressUpdater should be created in the main thread; KoProgressProxy must be, if it is gui subclass in the QApplication main thread. The other objects can be created in whatever thread one wants.

Also to prevent jumps in the progress-calculation and -display it is recommend to first create all the subtasks and then start to use setProgress on them.

Definition at line 23 of file KoProgressUpdater.cpp.

Member Enumeration Documentation

◆ Mode

enum KoProgressUpdater::Mode

Enumerator
Threaded
Unthreaded

Definition at line 58 of file KoProgressUpdater.h.

              {
        Threaded,
        Unthreaded
    };

Constructor & Destructor Documentation

◆ KoProgressUpdater() [1/2]

KoProgressUpdater::KoProgressUpdater	(	KoProgressProxy *	progressProxy,
		Mode	mode = Threaded )

explicit

Constructor.

Parameters

progressBar the progress bar to update.

Definition at line 70 of file KoProgressUpdater.cpp.

    : d (new Private(this, progressProxy, 0, mode))
{
    KIS_ASSERT_RECOVER_RETURN(progressProxy);
    connect(d->updateCompressor, SIGNAL(timeout()), SLOT(updateUi()));
    connect(this, SIGNAL(triggerUpdateAsynchronously()), d->updateCompressor, SLOT(start()));
    Q_EMIT triggerUpdateAsynchronously();
}

References connect(), d, KIS_ASSERT_RECOVER_RETURN, progressProxy(), start(), triggerUpdateAsynchronously(), and updateUi().

◆ KoProgressUpdater() [2/2]

KoProgressUpdater::KoProgressUpdater ( QPointer< KoUpdater > updater )

explicit

a special constructor for connecting the progress updater to a self-destructible KoUpdater object.

HACK ALERT: KoUpdater inherits KoProgressProxy, so be careful when constructing the updater and check which override is actually used.

Definition at line 79 of file KoProgressUpdater.cpp.

    : d (new Private(this, 0, updater, Unthreaded))
{
    KIS_ASSERT_RECOVER_RETURN(updater);
    connect(d->updateCompressor, SIGNAL(timeout()), SLOT(updateUi()));
    connect(this, SIGNAL(triggerUpdateAsynchronously()), d->updateCompressor, SLOT(start()));
    Q_EMIT triggerUpdateAsynchronously();
}

References connect(), d, KIS_ASSERT_RECOVER_RETURN, start(), triggerUpdateAsynchronously(), and updateUi().

◆ ~KoProgressUpdater()

KoProgressUpdater::~KoProgressUpdater ( )

override

destructor

Definition at line 88 of file KoProgressUpdater.cpp.

{
    if (d->progressProxy()) {
        d->progressProxy()->setRange(0, d->taskMax);
        d->progressProxy()->setValue(d->progressProxy()->maximum());
    }
 
    // make sure to stop the timer to avoid accessing
    // the data we are going to delete right now
    d->updateCompressor->stop();
 
    qDeleteAll(d->subtasks);
    d->subtasks.clear();
 
    delete d;
}

References d.

Member Function Documentation

◆ autoNestNames()

bool KoProgressUpdater::autoNestNames ( ) const

◆ cancel

void KoProgressUpdater::cancel ( )

slot

Cancelling the action will make each subtask be marked as 'interrupted' and set the total progress to 100%.

NOTE: cancelling mush happen from the same thread that KoProgressUpdater resides, which is usually GUI thread.

Definition at line 163 of file KoProgressUpdater.cpp.

{
    KIS_SAFE_ASSERT_RECOVER_RETURN(QThread::currentThread() == this->thread());
 
    QList<QPointer<KoUpdaterPrivate> > subtasks;
 
    {
        QMutexLocker l(&d->mutex);
        subtasks = d->subtasks;
    }
 
    Q_FOREACH (QPointer<KoUpdaterPrivate> updater, subtasks) {
        if (!updater) continue;
 
        updater->setProgress(100);
        updater->setInterrupted(true);
    }
    d->canceled = true;
 
    Q_EMIT triggerUpdateAsynchronously();
}

References d, KIS_SAFE_ASSERT_RECOVER_RETURN, subtasks, and triggerUpdateAsynchronously().

◆ clearState()

void KoProgressUpdater::clearState ( )

◆ interrupted()

bool KoProgressUpdater::interrupted ( ) const

Returns: true when the processing is interrupted

Definition at line 324 of file KoProgressUpdater.cpp.

{
    return d->canceled;
}

References d.

◆ Private()

KoProgressUpdater::Private	(	KoProgressUpdater *	_q,
		KoProgressProxy *	proxy,
		QPointer< KoUpdater >	parentUpdater,
		Mode	_mode )

inline

Definition at line 27 of file KoProgressUpdater.cpp.

        : q(_q)
        , parentProgressProxy(proxy)
        , parentUpdater(parentUpdater)
        , mode(_mode)
        , updateCompressor(new KisSignalCompressor(250, KisSignalCompressor::FIRST_ACTIVE, q))
        , canceled(false)
    {
    }

◆ progressProxy()

KoProgressProxy * KoProgressUpdater::progressProxy ( )

inline

Definition at line 61 of file KoProgressUpdater.cpp.

                                     {
        return parentUpdater ? parentUpdater : parentProgressProxy;
    }

◆ removePersistentSubtask()

void KoProgressUpdater::removePersistentSubtask ( QPointer< KoUpdater > updater )

Definition at line 143 of file KoProgressUpdater.cpp.

{
    {
        QMutexLocker l(&d->mutex);
 
        for (auto it = d->subtasks.begin(); it != d->subtasks.end();) {
            if ((*it)->connectedUpdater() != updater) {
                ++it;
            } else {
                KIS_SAFE_ASSERT_RECOVER_NOOP((*it)->isPersistent());
                (*it)->deleteLater();
                it = d->subtasks.erase(it);
                break;
            }
        }
    }
 
    Q_EMIT triggerUpdateAsynchronously();
}

References d, KIS_SAFE_ASSERT_RECOVER_NOOP, and triggerUpdateAsynchronously().

◆ setAutoNestNames()

void KoProgressUpdater::setAutoNestNames ( bool value )

Definition at line 339 of file KoProgressUpdater.cpp.

{
    d->autoNestNames = value;
}

References d, and value().

◆ setUpdateInterval()

void KoProgressUpdater::setUpdateInterval ( int ms )

Definition at line 329 of file KoProgressUpdater.cpp.

{
    d->updateCompressor->setDelay(ms);
}

References d.

◆ start()

void KoProgressUpdater::start	(	int	range = 100,
		const QString &	text = "" )

Start a new task.

This will invalidate any previously created subtasks and set the range of the progressBar as well as the text in the progressbar.

Parameters

range	the total range of progress bar makes.
text	The text to show in the progressBar.

See also: KoProgressProxy::setRange(); KoProgressProxy::setFormat()

Definition at line 105 of file KoProgressUpdater.cpp.

{
    {
        QMutexLocker l(&d->mutex);
        d->clearState();
        d->taskName = text;
        d->taskMax = range - 1;
        d->isStarted = true;
        d->currentProgress = 0;
    }
 
    Q_EMIT triggerUpdateAsynchronously();
}

References d, and triggerUpdateAsynchronously().

◆ startSubtask()

QPointer< KoUpdater > KoProgressUpdater::startSubtask	(	int	weight = 1,
		const QString &	name = QString(),
		bool	isPersistent = false )

After calling start() you can create any number of Updaters, one for each subtask.

Parameters

weight use a weight to specify the weight this subtask has compared to the rest of the subtasks.

KoProgressUpdater will delete the KoUpdater instances when a start() is called or when it is deleted. The KoUpdater pointers are packed in a QPointer so you can check whether they have been deleted before dereferencing.

Definition at line 119 of file KoProgressUpdater.cpp.

{
    if (!d->isStarted) {
        // lazy initialization for intermediate proxies
        start();
    }
 
    KoUpdaterPrivate *p = new KoUpdaterPrivate(weight, name, isPersistent);
 
    {
        QMutexLocker l(&d->mutex);
        d->subtasks.append(p);
    }
    connect(p, SIGNAL(sigUpdated()), SLOT(update()));
    connect(p, SIGNAL(sigCancelled()), SLOT(cancel()));
 
    QPointer<KoUpdater> updater = p->connectedUpdater();
 
    Q_EMIT triggerUpdateAsynchronously();
    return updater;
}

References cancel(), connect(), d, p, start(), triggerUpdateAsynchronously(), and update().

◆ triggerUpdateAsynchronously

void KoProgressUpdater::triggerUpdateAsynchronously ( )

signal

◆ update

void KoProgressUpdater::update ( )

privateslot

Definition at line 185 of file KoProgressUpdater.cpp.

{
    KIS_SAFE_ASSERT_RECOVER_RETURN(QThread::currentThread() == this->thread());
 
    if (d->mode == Unthreaded) {
        qApp->processEvents();
    }
 
    d->updateCompressor->start();
}

References d, KIS_SAFE_ASSERT_RECOVER_RETURN, and Unthreaded.

◆ updateInterval()

int KoProgressUpdater::updateInterval ( ) const

◆ updateParentText()

void KoProgressUpdater::updateParentText ( )

◆ updateUi

void KoProgressUpdater::updateUi ( )

privateslot

Definition at line 196 of file KoProgressUpdater.cpp.

{
    KIS_SAFE_ASSERT_RECOVER_RETURN(QThread::currentThread() == this->thread());
 
    // This function runs in the app main thread. All the progress
    // updates arrive at the KoUpdaterPrivate instances through
    // queued connections, so until we relinquish control to the
    // event loop, the progress values cannot change, and that
    // won't happen until we return from this function (which is
    // triggered by a timer)
 
    {
        QMutexLocker l(&d->mutex);
 
        if (!d->subtasks.isEmpty()) {
            int totalProgress = 0;
            int totalWeight = 0;
            d->isUndefinedState = false;
 
            Q_FOREACH (QPointer<KoUpdaterPrivate> updater, d->subtasks) {
                if (updater->interrupted()) {
                    d->currentProgress = -1;
                    break;
                }
 
                if (!updater->hasValidRange()) {
                    totalWeight = 0;
                    totalProgress = 0;
                    d->isUndefinedState = true;
                    break;
                }
 
                if (updater->isPersistent() && updater->isCompleted()) {
                    continue;
                }
 
                const int progress = qBound(0, updater->progress(), 100);
                totalProgress += progress * updater->weight();
                totalWeight += updater->weight();
            }
 
            const int progressPercent = totalWeight > 0 ? totalProgress / totalWeight : -1;
 
            d->currentProgress =
                    d->taskMax == 99 ?
                        progressPercent :
                        qRound(qreal(progressPercent) * d->taskMax / 99.0);
        }
 
    }
 
    if (d->progressProxy()) {
        if (!d->isUndefinedState) {
            d->progressProxy()->setRange(0, d->taskMax);
 
            if (d->currentProgress == -1) {
                d->currentProgress = d->progressProxy()->maximum();
            }
 
            if (d->currentProgress >= d->progressProxy()->maximum()) {
                {
                    QMutexLocker l(&d->mutex);
                    d->clearState();
                }
                d->progressProxy()->setRange(0, d->taskMax);
                d->progressProxy()->setValue(d->progressProxy()->maximum());
            } else {
                d->progressProxy()->setValue(d->currentProgress);
            }
        } else {
            d->progressProxy()->setRange(0,0);
            d->progressProxy()->setValue(0);
        }
 
        d->updateParentText();
    }
}

References d, and KIS_SAFE_ASSERT_RECOVER_RETURN.

Member Data Documentation

◆ autoNestNames

bool KoProgressUpdater::autoNestNames = false

Definition at line 51 of file KoProgressUpdater.cpp.

◆ canceled

bool KoProgressUpdater::canceled

Definition at line 49 of file KoProgressUpdater.cpp.

◆ currentProgress

int KoProgressUpdater::currentProgress = 0

Definition at line 45 of file KoProgressUpdater.cpp.

◆ d

Private* const KoProgressUpdater::d

private

Definition at line 142 of file KoProgressUpdater.h.

◆ isStarted

bool KoProgressUpdater::isStarted = false

Definition at line 54 of file KoProgressUpdater.cpp.

◆ isUndefinedState

bool KoProgressUpdater::isUndefinedState = false

Definition at line 46 of file KoProgressUpdater.cpp.

◆ mode

Mode KoProgressUpdater::mode

Definition at line 44 of file KoProgressUpdater.cpp.

◆ mutex

QMutex KoProgressUpdater::mutex

Definition at line 56 of file KoProgressUpdater.cpp.

◆ parentProgressProxy

KoProgressProxy* KoProgressUpdater::parentProgressProxy

private

Definition at line 40 of file KoProgressUpdater.cpp.

◆ parentUpdater

QPointer<KoUpdater> KoProgressUpdater::parentUpdater

private

Definition at line 41 of file KoProgressUpdater.cpp.

◆ q

KoProgressUpdater* KoProgressUpdater::q

Definition at line 37 of file KoProgressUpdater.cpp.

◆ subtasks

QList<QPointer<KoUpdaterPrivate> > KoProgressUpdater::subtasks

Definition at line 48 of file KoProgressUpdater.cpp.

◆ taskMax

int KoProgressUpdater::taskMax = 99

Definition at line 53 of file KoProgressUpdater.cpp.

◆ taskName

QString KoProgressUpdater::taskName

Definition at line 52 of file KoProgressUpdater.cpp.

◆ updateCompressor

KisSignalCompressor* KoProgressUpdater::updateCompressor

Definition at line 47 of file KoProgressUpdater.cpp.

◆ updateInterval

int KoProgressUpdater::updateInterval = 250

Definition at line 50 of file KoProgressUpdater.cpp.

The documentation for this class was generated from the following files:

libs/widgetutils/KoProgressUpdater.cpp
libs/widgetutils/KoProgressUpdater.h

Public Types

Public Slots

Signals

Public Member Functions

Public Attributes

Private Slots

Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Mode

Constructor & Destructor Documentation

◆ KoProgressUpdater() [1/2]

◆ KoProgressUpdater() [2/2]

◆ ~KoProgressUpdater()

Member Function Documentation

◆ autoNestNames()

◆ cancel

◆ clearState()

◆ interrupted()

◆ Private()

◆ progressProxy()

◆ removePersistentSubtask()

◆ setAutoNestNames()

◆ setUpdateInterval()

◆ start()

◆ startSubtask()

◆ triggerUpdateAsynchronously

◆ update

◆ updateInterval()

◆ updateParentText()

◆ updateUi

Member Data Documentation

◆ autoNestNames

◆ canceled

◆ currentProgress

◆ d

◆ isStarted

◆ isUndefinedState

◆ mode

◆ mutex

◆ parentProgressProxy

◆ parentUpdater

◆ q

◆ subtasks

◆ taskMax

◆ taskName

◆ updateCompressor

◆ updateInterval