Taskbar related class docs and overviews

Change-Id: Ib5aebea73f9637d62dc64f71050bb07b1998a66d
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@digia.com>
Reviewed-by: Caroline Chao <caroline.chao@digia.com>
Reviewed-by: Ivan Vizir <define-true-false@yandex.com>

8 files changed, 128 insertions, 16 deletions

diff --git a/src/winextras/doc/images/taskbar-button.png b/src/winextras/doc/images/taskbar-button.png
new file mode 100644
index 0000000..8c585f4
--- /dev/null
+++ b/src/winextras/doc/images/taskbar-button.png
diff --git a/src/winextras/doc/images/taskbar-progress-indeterminate.png b/src/winextras/doc/images/taskbar-progress-indeterminate.png
new file mode 100644
index 0000000..800cf51
--- /dev/null
+++ b/src/winextras/doc/images/taskbar-progress-indeterminate.png
diff --git a/src/winextras/doc/images/taskbar-progress-paused.png b/src/winextras/doc/images/taskbar-progress-paused.png
new file mode 100644
index 0000000..55383fd
--- /dev/null
+++ b/src/winextras/doc/images/taskbar-progress-paused.png
diff --git a/src/winextras/doc/images/taskbar-progress-stopped.png b/src/winextras/doc/images/taskbar-progress-stopped.png
new file mode 100644
index 0000000..f4b6dc1
--- /dev/null
+++ b/src/winextras/doc/images/taskbar-progress-stopped.png
diff --git a/src/winextras/doc/images/taskbar-progress.png b/src/winextras/doc/images/taskbar-progress.png
new file mode 100644
index 0000000..97bb286
--- /dev/null
+++ b/src/winextras/doc/images/taskbar-progress.png
diff --git a/src/winextras/doc/snippets/code/taskbar.cpp b/src/winextras/doc/snippets/code/taskbar.cpp
new file mode 100644
index 0000000..5932ee2
--- /dev/null
+++ b/src/winextras/doc/snippets/code/taskbar.cpp
@@ -0,0 +1,55 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtWinExtras>
+
+void initializeTaskbarButton(QWidget *widget)
+{
+    Q_ASSERT(widget->windowHandle()); // Note: this requires the window to be shown.
+//! [taskbar_cpp]
+    QWinTaskbarButton *button = new QWinTaskbarButton(widget);
+    button->setWindow(widget->windowHandle());
+    button->setOverlayIcon(QIcon(":/loading.png"));
+
+    QWinTaskbarProgress *progress = button->progress();
+    progress->setVisible(true);
+    progress->setValue(50);
+//! [taskbar_cpp]
+}
diff --git a/src/winextras/doc/src/qtwinextras-overview.qdoc b/src/winextras/doc/src/qtwinextras-overview.qdoc
index 3ccb90a..7c7730e 100644
--- a/src/winextras/doc/src/qtwinextras-overview.qdoc
+++ b/src/winextras/doc/src/qtwinextras-overview.qdoc
@@ -83,10 +83,19 @@
 
     \section2 Overlay Icons and Progress Indicators
 
-    You can use the QWinTaskbarButton class to set overlay icons and to display
-    a progress indicator on a taskbar button. The overlay icons indicate changes
-    in the state of the application. The progress indicator shows how
-    time-consuming tasks are progressing.
+    You can use the QWinTaskbarButton class to set an overlay icon and the
+    QWinTaskbarProgress class to display a progress indicator on a taskbar button.
+    An overlay icon indicates change in the state of the application. A progress
+    indicator shows how time-consuming tasks are progressing.
+
+    \image taskbar-button.png Taskbar Button
+
+    \section3 Taskbar Example
+
+    The following example code illustrates how to use the QWinTaskbarButton
+    and QWinTaskbarProgress classes to adjust the look of the taskbar button:
+
+    \snippet code/taskbar.cpp taskbar_cpp
 
     \section2 Jump Lists
 
diff --git a/src/winextras/qwintaskbarprogress.cpp b/src/winextras/qwintaskbarprogress.cpp
index 93bae9d..b38d716 100644
--- a/src/winextras/qwintaskbarprogress.cpp
+++ b/src/winextras/qwintaskbarprogress.cpp
@@ -46,18 +46,46 @@ QT_BEGIN_NAMESPACE
 /*!
     \class QWinTaskbarProgress
     \inmodule QtWinExtras
-    \brief The QWinTaskbarProgress class represents the Windows taskbar progress indicator.
+    \brief The QWinTaskbarProgress class represents a progress indicator in the Windows taskbar.
 
     \since 5.2
 
-    The QWinTaskbarProgress class enables you to to display a progress indicator
-    on a taskbar button.
+    A progress indicator is used to give the user an indication of the progress
+    of an operation and to reassure them that the application is still running.
+
+    The progress indicator uses the concept of \e steps. It is set up by specifying
+    the minimum and maximum possible step values, and it will display the percentage
+    of steps that have been completed when you later give it the current step value.
+    The percentage is calculated by dividing the progress (value() - minimum())
+    divided by maximum() - minimum().
+
+    The minimum and maximum number of steps can be specified by calling setMinimum()
+    and setMaximum(). The current number of steps is set with setValue(). The progress
+    indicator can be rewound to the beginning with reset().
+
+    If minimum and maximum both are set to \c 0, the indicator shows up as a busy
+    (indeterminate) indicator instead of a percentage of steps. This is useful when
+    it is not possible to determine the number of steps.
+
+    \table
+    \row \li \inlineimage taskbar-progress.png Screenshot of a progress indicator
+         \li A progress indicator at 50%.
+    \row \li \inlineimage taskbar-progress-paused.png Screenshot of a paused progress indicator
+         \li A paused progress indicator at 50%.
+    \row \li \inlineimage taskbar-progress-stopped.png Screenshot of a stopped progress indicator
+        \li A stopped progress indicator at 50%.
+    \row \li \inlineimage taskbar-progress-indeterminate.png Screenshot of an indeterminate progress indicator
+         \li An indeterminate progress indicator.
+    \endtable
+
+    \note The final appearance of the progress indicator varies depending on the active Windows theme.
+
+    \sa QWinTaskbarButton
  */
 
 /*!
-    \fn void QWinTaskbarProgress::valueChanged(int value)
-
-    This signal is emitted when the progress indicator \a value changes.
+    \fn void QWinTaskbarProgress::pausedChanged(bool paused)
+    \internal (for QWinTaskbarButton and QML compatibility)
  */
 
 /*!
@@ -158,7 +186,7 @@ void QWinTaskbarProgress::setMaximum(int maximum)
 
 /*!
     \property QWinTaskbarProgress::visible
-    \brief the progress indicator is visible.
+    \brief whether the progress indicator is visible.
 
     The default value is \c false.
  */
@@ -228,9 +256,16 @@ void QWinTaskbarProgress::reset()
 
 /*!
     \property QWinTaskbarProgress::paused
-    \brief the progress indicator is paused.
+    \brief whether the progress indicator is paused.
 
     The default value is \c false.
+
+    The final appearance of a paused progress indicator depends on the active
+    Windows theme. Typically, a paused progress indicator turns yellow to indicate
+    that the progress is currently paused. Unlike a \l stopped progress indicator,
+    a paused progress should not be used to indicate an error.
+
+    \sa pause(), resume()
  */
 bool QWinTaskbarProgress::isPaused() const
 {
@@ -249,7 +284,9 @@ void QWinTaskbarProgress::setPaused(bool paused)
 }
 
 /*!
-    Pause the progress indicator.
+    Pauses the progress indicator.
+
+    \sa paused
  */
 void QWinTaskbarProgress::pause()
 {
@@ -257,7 +294,9 @@ void QWinTaskbarProgress::pause()
 }
 
 /*!
-    Resume a paused or stopped progress indicator.
+    Resumes a paused or stopped progress indicator.
+
+    \sa paused, stopped
  */
 void QWinTaskbarProgress::resume()
 {
@@ -271,9 +310,16 @@ void QWinTaskbarProgress::resume()
 
 /*!
     \property QWinTaskbarProgress::stopped
-    \brief the progress indicator is stopped.
+    \brief whether the progress indicator is stopped.
 
     The default value is \c false.
+
+    The final appearance of a stopped progress indicator depends on the active
+    Windows theme. Typically, a stopped progress indicator turns red to indicate
+    that the progress is currently stopped. Unlike a \l paused progress indicator,
+    a stopped progress may be used to indicate an error.
+
+    \sa stop(), resume()
  */
 bool QWinTaskbarProgress::isStopped() const
 {
@@ -282,7 +328,9 @@ bool QWinTaskbarProgress::isStopped() const
 }
 
 /*!
-    Stop the progress indicator.
+    Stops the progress indicator.
+
+    \sa stopped
  */
 void QWinTaskbarProgress::stop()
 {