From 76be80427f050efe5600a9d95cb41ecdb44d9420 Mon Sep 17 00:00:00 2001
From: con <qtc-committer@nokia.com>
Date: Mon, 21 Dec 2009 17:11:47 +0100
Subject: [PATCH] More documentation for ProgressManager related tasks.

---
 .../progressmanager/futureprogress.cpp        | 69 +++++++++++++++++++
 .../progressmanager/progressmanager.cpp       | 12 +++-
 2 files changed, 79 insertions(+), 2 deletions(-)

diff --git a/src/plugins/coreplugin/progressmanager/futureprogress.cpp b/src/plugins/coreplugin/progressmanager/futureprogress.cpp
index 6638b3f7f5e..9ff3c2384a7 100644
--- a/src/plugins/coreplugin/progressmanager/futureprogress.cpp
+++ b/src/plugins/coreplugin/progressmanager/futureprogress.cpp
@@ -39,6 +39,41 @@
 
 using namespace Core;
 
+/*!
+    \mainclass
+    \class Core::FutureProgress
+    \brief The FutureProgress class is used to adapt the appearance of
+    progress indicators that were created through the ProgressManager class.
+
+    Use the instance of this class that was returned by
+    ProgressManager::addTask() to define a widget that
+    should be shown below the progress bar, or to change the
+    progress title.
+    Also use it to react on the event that the user clicks on
+    the progress indicator (which can be used to e.g. open a more detailed
+    view, or the results of the task).
+*/
+
+/*!
+    \fn void FutureProgress::clicked()
+    Connect to this signal to get informed when the user clicks on the
+    progress indicator.
+*/
+
+/*!
+    \fn void FutureProgress::finished()
+    Another way to get informed when the task has finished.
+*/
+
+/*!
+    \fn QWidget FutureProgress::widget() const
+    Returns the custom widget that is shown below the progress indicator.
+*/
+
+/*!
+    \fn FutureProgress::FutureProgress(QWidget *parent)
+    \internal
+*/
 FutureProgress::FutureProgress(QWidget *parent)
         : QWidget(parent),
         m_progress(new ProgressBar),
@@ -63,12 +98,22 @@ FutureProgress::FutureProgress(QWidget *parent)
     connect(m_progress, SIGNAL(clicked()), this, SLOT(cancel()));
 }
 
+/*!
+    \fn FutureProgress::~FutureProgress()
+    \internal
+*/
 FutureProgress::~FutureProgress()
 {
     if (m_widget)
         delete m_widget;
 }
 
+/*!
+    \fn void FutureProgress::setWidget(QWidget *widget)
+    Sets the \a widget to show below the progress bar.
+    This will be destroyed when the progress indicator is destroyed.
+    Default is to show no widget below the progress indicator.
+*/
 void FutureProgress::setWidget(QWidget *widget)
 {
     if (m_widget)
@@ -81,11 +126,19 @@ void FutureProgress::setWidget(QWidget *widget)
         m_widgetLayout->addWidget(m_widget);
 }
 
+/*!
+    \fn void FutureProgress::setTitle(const QString &title)
+    Changes the \a title of the progress indicator.
+*/
 void FutureProgress::setTitle(const QString &title)
 {
     m_progress->setTitle(title);
 }
 
+/*!
+    \fn QString FutureProgress::title() const
+    Returns the title of the progress indicator.
+*/
 QString FutureProgress::title() const
 {
     return m_progress->title();
@@ -144,16 +197,28 @@ void FutureProgress::setProgressText(const QString &text)
     setToolTip(text);
 }
 
+/*!
+    \fn void FutureProgress::setFuture(const QFuture<void> &future)
+    \internal
+*/
 void FutureProgress::setFuture(const QFuture<void> &future)
 {
     m_watcher.setFuture(future);
 }
 
+/*!
+    \fn QFuture<void> FutureProgress::future() const
+    Returns a QFuture object that represents this running task.
+*/
 QFuture<void> FutureProgress::future() const
 {
     return m_watcher.future();
 }
 
+/*!
+    \fn void FutureProgress::mousePressEvent(QMouseEvent *event)
+    \internal
+*/
 void FutureProgress::mousePressEvent(QMouseEvent *event)
 {
     if (event->button() == Qt::LeftButton)
@@ -161,6 +226,10 @@ void FutureProgress::mousePressEvent(QMouseEvent *event)
     QWidget::mousePressEvent(event);
 }
 
+/*!
+    \fn bool FutureProgress::hasError() const
+    Returns the error state of this progress indicator.
+*/
 bool FutureProgress::hasError() const
 {
     return m_progress->hasError();
diff --git a/src/plugins/coreplugin/progressmanager/progressmanager.cpp b/src/plugins/coreplugin/progressmanager/progressmanager.cpp
index 7b0afe2bf97..2dd6ea3ebd3 100644
--- a/src/plugins/coreplugin/progressmanager/progressmanager.cpp
+++ b/src/plugins/coreplugin/progressmanager/progressmanager.cpp
@@ -166,6 +166,13 @@ using namespace Core::Internal;
     in QFutureInterface. After the long taking operation has finished,
     we report so through the QFutureInterface object, and delete it
     afterwards.
+
+    \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.
 */
 
 /*!
@@ -193,13 +200,14 @@ using namespace Core::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.
+    Shows a progress indicator for task given by the QFuture object \a future.
     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.
+    which can be used to further customize. The FutureProgress object's
+    life is managed by the ProgressManager and is guaranteed to live
 */
 
 /*!