1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
/* This file is part of the KDE project
* Copyright (C) 2006-2007 Thomas Zander <zander@kde.org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* 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., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
*/
#ifndef KOPROGRESSUPDATER_H
#define KOPROGRESSUPDATER_H
#include "kowidgetutils_export.h"
#include <QString>
#include <QObject>
#include <QPointer>
class KoUpdater;
class KoProgressProxy;
class QTextStream;
class QTime;
/**
* 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:
* @code
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);
@endcode
* 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 recommed
* to first create all the subtasks and then start to use setProgress on them.
*/
class KOWIDGETUTILS_EXPORT KoProgressUpdater : public QObject
{
Q_OBJECT
public:
enum Mode {
Threaded,
Unthreaded
};
/**
* Constructor.
* @param progressBar the progress bar to update.
*/
explicit KoProgressUpdater(KoProgressProxy *progressBar, Mode mode = Threaded,
QTextStream *output = 0);
/// destructor
~KoProgressUpdater() override;
/**
* 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.
*
* @param range the total range of progress bar makes.
* @param text The text to show in the progressBar.
* @see KoProgressProxy::setRange()
* @see KoProgressProxy::setFormat()
*/
void start(int range = 100, const QString &text = QLatin1String("%p%"));
/**
* After calling start() you can create any number of Updaters,
* one for each subtask. @param 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.
*/
QPointer<KoUpdater> startSubtask(int weight=1,
const QString &name = QString());
/**
* Cancelling the action will make each subtask be marked as 'interrupted' and
* set the total progress to 100%.
*/
void cancel();
/**
* Set the time with respect to which the progress events are logged.
*/
void setReferenceTime(const QTime &referenceTime);
/**
* Get the time with respect to which the progress events are logged.
*/
QTime referenceTime() const;
/**
* @return true when the processing is interrupted
*/
bool interrupted() const;
/**
* @return true when the output has been set
*/
bool hasOutput() const;
private Q_SLOTS:
void update();
void updateUi();
private:
class Private;
Private *const d;
};
#endif
|
