progressmanager.cpp 11.7 KB
Newer Older
1
/**************************************************************************
con's avatar
con committed
2
3
4
**
** This file is part of Qt Creator
**
5
** Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
con's avatar
con committed
6
**
7
** Contact: Nokia Corporation (qt-info@nokia.com)
con's avatar
con committed
8
**
9
** Commercial Usage
10
**
11
12
13
14
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
15
**
16
** GNU Lesser General Public License Usage
17
**
18
19
20
21
22
23
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24
**
25
** If you are unsure which license is appropriate for your use, please
hjk's avatar
hjk committed
26
** contact the sales department at http://qt.nokia.com/contact.
con's avatar
con committed
27
**
28
**************************************************************************/
hjk's avatar
hjk committed
29

30
#include "progressmanager_p.h"
con's avatar
con committed
31
32
#include "progressview.h"
#include "coreconstants.h"
33
#include "icore.h"
con's avatar
con committed
34
35
#include "uniqueidmanager.h"

hjk's avatar
hjk committed
36
37
#include <utils/qtcassert.h>

con's avatar
con committed
38
39
40
using namespace Core;
using namespace Core::Internal;

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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
/*!
    \mainclass
    \class Core::ProgressManager
    \brief The ProgressManager class is used to show a user interface
    for running tasks in Qt Creator.

    It tracks the progress of a task that it is told
    about, and shows a progress indicator in the left hand tool bar
    of Qt Creator's main window to the user.
    The progress indicator also allows the user to cancel the task.

    You get the single instance of this class via the
    Core::ICore::progressManager() method.

    \section1 Registering a task
    The ProgressManager API uses QtConcurrent as the basis for defining
    tasks. A task consists of the following properties:

    \table
    \header
        \o Property
        \o Type
        \o Description
    \row
        \o Task abstraction
        \o \c QFuture<void>
        \o A \c QFuture object that represents the task which is
           responsible for reporting the state of the task. See below
           for coding patterns how to create this object for your
           specific task.
    \row
        \o Title
        \o \c QString
        \o A very short title describing your task. This is shown
           as a title over the progress bar.
    \row
        \o Type
        \o \c QString
        \o A string identifier that is used to group different tasks that
           belong together.
           For example, all the search operations use the same type
           identifier.
    \row
        \o Flags
        \o \l ProgressManager::ProgressFlags
        \o Additional flags that specify how the progress bar should
           be presented to the user.
    \endtable

    To register a task you create your \c QFuture<void> object, and call
    addTask(). This method returns a
    \l{Core::FutureProgress}{FutureProgress}
    object that you can use to further customize the progress bar's appearance.
    See the \l{Core::FutureProgress}{FutureProgress} documentation for
    details.

    In the following you will learn about two common patterns how to
    create the \c QFuture<void> object for your task.

    \section2 Create a threaded task with QtConcurrent
    The first option is to directly use QtConcurrent to actually
    start a task concurrently in a different thread.
    QtConcurrent has several different methods to run e.g.
    a class method in a different thread. Qt Creator itself
    adds a few more in \c{src/libs/qtconcurrent/runextensions.h}.
    The QtConcurrent methods to run a concurrent task return a
    \c QFuture object. This is what you want to give the
    ProgressManager in the addTask() method.

    Have a look at e.g Locator::ILocatorFilter. Locator filters implement
    a method \c refresh which takes a \c QFutureInterface object
    as a parameter. These methods look something like:
    \code
    void Filter::refresh(QFutureInterface<void> &future) {
        future.setProgressRange(0, MAX);
        ...
        while (!future.isCanceled()) {
            // Do a part of the long stuff
            ...
            future.setProgressValue(currentProgress);
            ...
        }
    }
    \endcode

    The actual refresh, which calls all the filters' refresh methods
    in a different thread, looks like this:
    \code
    QFuture<void> task = QtConcurrent::run(&ILocatorFilter::refresh, filters);
    Core::FutureProgress *progress = Core::ICore::instance()
            ->progressManager()->addTask(task, tr("Indexing"),
                                         Locator::Constants::TASK_INDEX);
    \endcode
    First, we tell QtConcurrent to start a thread which calls all the filters'
    refresh method. After that we register the returned QFuture object
    with the ProgressManager.

    \section2 Manually create QtConcurrent objects for your thread
    If your task has its own means to create and run a thread,
    you need to create the necessary objects yourselves, and
    report the start/stop state.

    \code
    // We are already running in a different thread here
    QFutureInterface<void> *progressObject = new QFutureInterface<void>;
    progressObject->setProgressRange(0, MAX);
    Core::ICore::instance()->progressManager()->addTask(
        progressObject->future(),
        tr("DoIt"), MYTASKTYPE);
    progressObject->reportStarted();
    // Do something
    ...
    progressObject->setProgressValue(currentProgress);
    ...
    // We have done what we needed to do
    progressObject->reportFinished();
    delete progressObject;
    \endcode
    In the first line we create the QFutureInterface object that will be
    our way for reporting the task's state.
    The first thing we report is the expected range of the progress values.
    We register the task with the ProgressManager, using the internal
    QFuture object that has been created for our QFutureInterface object.
    Next we report that the task has begun and start doing our actual
    work, regularly reporting the progress via the methods
    in QFutureInterface. After the long taking operation has finished,
    we report so through the QFutureInterface object, and delete it
    afterwards.
*/

/*!
    \enum Core::ProgressManager::ProgressFlag
    Additional flags that specify details in behavior. The
    default for a task is to not have any of these flags set.
    \value KeepOnFinish
        The progress indicator stays visible after the task has finished.
    \value ShowInApplicationIcon
        The progress indicator for this task is additionally
        shown in the application icon in the system's task bar or dock, on
        platforms that support that (at the moment Windows 7 and Mac OS X).
*/

/*!
    \fn Core::ProgressManager::ProgressManager(QObject *parent = 0)
    \internal
*/

/*!
    \fn Core::ProgressManager::~ProgressManager()
    \internal
*/

/*!
    \fn FutureProgress *Core::ProgressManager::addTask(const QFuture<void> &future, const QString &title, const QString &type, ProgressFlags flags = 0)

    Shows a progress indicator for the given task.
    The progress indicator shows the specified \a title along with the progress bar.
    The \a type of a task will specify a logical grouping with other
    running tasks. Via the \a flags parameter you can e.g. let the
    progress indicator stay visible after the task has finished.
    Returns an object that represents the created progress indicator,
    which can be used to further customize.
*/

/*!
    \fn void Core::ProgressManager::setApplicationLabel(const QString &text)

    Shows the given \a text in a platform dependent way in the application
    icon in the system's task bar or dock. This is used
    to show the number of build errors on Windows 7 and Mac OS X.
*/

/*!
    \fn void Core::ProgressManager::cancelTasks(const QString &type)

    Schedules a cancel for all running tasks of the given \a type.
    Please note that the cancel functionality depends on the
    running task to actually check the \c QFutureInterface::isCanceled
    property.
*/

/*!
    \fn void Core::ProgressManager::taskStarted(const QString &type)

    Sent whenever a task of a given \a type is started.
*/

/*!
    \fn void Core::ProgressManager::allTasksFinished(const QString &type)

    Sent when all tasks of a \a type have finished.
*/

234
ProgressManagerPrivate::ProgressManagerPrivate(QObject *parent)
235
236
  : ProgressManager(parent),
    m_applicationTask(0)
con's avatar
con committed
237
238
{
    m_progressView = new ProgressView;
239
    ICore *core = ICore::instance();
con's avatar
con committed
240
241
242
    connect(core, SIGNAL(coreAboutToClose()), this, SLOT(cancelAllRunningTasks()));
}

243
ProgressManagerPrivate::~ProgressManagerPrivate()
con's avatar
con committed
244
{
245
    cleanup();
con's avatar
con committed
246
247
}

248
void ProgressManagerPrivate::cancelTasks(const QString &type)
con's avatar
con committed
249
{
250
    bool found = false;
con's avatar
con committed
251
252
253
254
255
256
    QMap<QFutureWatcher<void> *, QString>::iterator task = m_runningTasks.begin();
    while (task != m_runningTasks.end()) {
        if (task.value() != type) {
            ++task;
            continue;
        }
257
        found = true;
con's avatar
con committed
258
        disconnect(task.key(), SIGNAL(finished()), this, SLOT(taskFinished()));
259
260
        if (m_applicationTask == task.key())
            disconnectApplicationTask();
con's avatar
con committed
261
262
263
264
        task.key()->cancel();
        delete task.key();
        task = m_runningTasks.erase(task);
    }
265
266
267
    if (found) {
        emit allTasksFinished(type);
    }
con's avatar
con committed
268
269
}

270
void ProgressManagerPrivate::cancelAllRunningTasks()
con's avatar
con committed
271
272
273
274
{
    QMap<QFutureWatcher<void> *, QString>::const_iterator task = m_runningTasks.constBegin();
    while (task != m_runningTasks.constEnd()) {
        disconnect(task.key(), SIGNAL(finished()), this, SLOT(taskFinished()));
275
276
        if (m_applicationTask == task.key())
            disconnectApplicationTask();
con's avatar
con committed
277
278
279
280
281
282
283
        task.key()->cancel();
        delete task.key();
        ++task;
    }
    m_runningTasks.clear();
}

284
285
FutureProgress *ProgressManagerPrivate::addTask(const QFuture<void> &future, const QString &title,
                                                const QString &type, ProgressFlags flags)
con's avatar
con committed
286
287
288
289
{
    QFutureWatcher<void> *watcher = new QFutureWatcher<void>();
    m_runningTasks.insert(watcher, type);
    connect(watcher, SIGNAL(finished()), this, SLOT(taskFinished()));
290
291
292
293
294
295
296
297
    if (flags & ShowInApplicationIcon) {
        m_applicationTask = watcher;
        connect(m_applicationTask, SIGNAL(progressRangeChanged(int,int)),
                this, SLOT(setApplicationProgressRange(int,int)));
        connect(m_applicationTask, SIGNAL(progressValueChanged(int)),
                this, SLOT(setApplicationProgressValue(int)));
        setApplicationProgressVisible(true);
    }
con's avatar
con committed
298
    watcher->setFuture(future);
299
    emit taskStarted(type);
300
    return m_progressView->addTask(future, title, type, flags);
con's avatar
con committed
301
302
}

303
QWidget *ProgressManagerPrivate::progressView()
con's avatar
con committed
304
305
306
307
{
    return m_progressView;
}

308
void ProgressManagerPrivate::taskFinished()
con's avatar
con committed
309
310
{
    QObject *taskObject = sender();
hjk's avatar
hjk committed
311
    QTC_ASSERT(taskObject, return);
con's avatar
con committed
312
    QFutureWatcher<void> *task = static_cast<QFutureWatcher<void> *>(taskObject);
313
314
    if (m_applicationTask == task)
        disconnectApplicationTask();
315
    QString type = m_runningTasks.value(task);
con's avatar
con committed
316
317
    m_runningTasks.remove(task);
    delete task;
318

con's avatar
con committed
319
    if (!m_runningTasks.key(type, 0)) {
320
321
        emit allTasksFinished(type);
    }
con's avatar
con committed
322
}
323
324
325
326
327
328
329
330
331
332

void ProgressManagerPrivate::disconnectApplicationTask()
{
    disconnect(m_applicationTask, SIGNAL(progressRangeChanged(int,int)),
            this, SLOT(setApplicationProgressRange(int,int)));
    disconnect(m_applicationTask, SIGNAL(progressValueChanged(int)),
            this, SLOT(setApplicationProgressValue(int)));
    setApplicationProgressVisible(false);
    m_applicationTask = 0;
}