progressmanager.cpp 12.1 KB
Newer Older
1
/**************************************************************************
con's avatar
con committed
2
3
4
**
** This file is part of Qt Creator
**
hjk's avatar
hjk committed
5
** Copyright (c) 2010 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

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

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

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
156
157
158
159
160
161
162
163
164
165
166
167
/*!
    \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.
168
169
170
171
172
173
174

    \section1 Customizing progress appearance

    You can set a custom widget to show below the progress bar itself,
    using the FutureProgress object returned by the addTask() method.
    Also use this object to get notified when the user clicks on the
    progress indicator.
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
*/

/*!
    \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)

202
    Shows a progress indicator for task given by the QFuture object \a future.
203
204
205
206
207
    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,
208
209
    which can be used to further customize. The FutureProgress object's
    life is managed by the ProgressManager and is guaranteed to live
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
*/

/*!
    \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.
*/

241
ProgressManagerPrivate::ProgressManagerPrivate(QObject *parent)
242
243
  : ProgressManager(parent),
    m_applicationTask(0)
con's avatar
con committed
244
245
{
    m_progressView = new ProgressView;
246
    ICore *core = ICore::instance();
con's avatar
con committed
247
248
249
    connect(core, SIGNAL(coreAboutToClose()), this, SLOT(cancelAllRunningTasks()));
}

250
ProgressManagerPrivate::~ProgressManagerPrivate()
con's avatar
con committed
251
{
252
    cleanup();
con's avatar
con committed
253
254
}

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

277
void ProgressManagerPrivate::cancelAllRunningTasks()
con's avatar
con committed
278
279
280
281
{
    QMap<QFutureWatcher<void> *, QString>::const_iterator task = m_runningTasks.constBegin();
    while (task != m_runningTasks.constEnd()) {
        disconnect(task.key(), SIGNAL(finished()), this, SLOT(taskFinished()));
282
283
        if (m_applicationTask == task.key())
            disconnectApplicationTask();
con's avatar
con committed
284
285
286
287
288
289
290
        task.key()->cancel();
        delete task.key();
        ++task;
    }
    m_runningTasks.clear();
}

291
292
FutureProgress *ProgressManagerPrivate::addTask(const QFuture<void> &future, const QString &title,
                                                const QString &type, ProgressFlags flags)
con's avatar
con committed
293
294
295
296
{
    QFutureWatcher<void> *watcher = new QFutureWatcher<void>();
    m_runningTasks.insert(watcher, type);
    connect(watcher, SIGNAL(finished()), this, SLOT(taskFinished()));
297
298
299
300
301
302
303
304
    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
305
    watcher->setFuture(future);
306
    emit taskStarted(type);
307
    return m_progressView->addTask(future, title, type, flags);
con's avatar
con committed
308
309
}

310
QWidget *ProgressManagerPrivate::progressView()
con's avatar
con committed
311
312
313
314
{
    return m_progressView;
}

315
void ProgressManagerPrivate::taskFinished()
con's avatar
con committed
316
317
{
    QObject *taskObject = sender();
hjk's avatar
hjk committed
318
    QTC_ASSERT(taskObject, return);
con's avatar
con committed
319
    QFutureWatcher<void> *task = static_cast<QFutureWatcher<void> *>(taskObject);
320
321
    if (m_applicationTask == task)
        disconnectApplicationTask();
322
    QString type = m_runningTasks.value(task);
con's avatar
con committed
323
324
    m_runningTasks.remove(task);
    delete task;
325

con's avatar
con committed
326
    if (!m_runningTasks.key(type, 0)) {
327
328
        emit allTasksFinished(type);
    }
con's avatar
con committed
329
}
330
331
332
333
334
335
336
337
338
339

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;
}