From b4c0ff2d9ef181ae0564764c75118ca974ebbc00 Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Mon, 9 Sep 2013 13:55:50 +0200 Subject: Taskbar related class docs and overviews Change-Id: Ib5aebea73f9637d62dc64f71050bb07b1998a66d Reviewed-by: Friedemann Kleint Reviewed-by: Caroline Chao Reviewed-by: Ivan Vizir --- src/winextras/doc/images/taskbar-button.png | Bin 0 -> 7844 bytes .../doc/images/taskbar-progress-indeterminate.png | Bin 0 -> 8032 bytes .../doc/images/taskbar-progress-paused.png | Bin 0 -> 7153 bytes .../doc/images/taskbar-progress-stopped.png | Bin 0 -> 7203 bytes src/winextras/doc/images/taskbar-progress.png | Bin 0 -> 7374 bytes src/winextras/doc/snippets/code/taskbar.cpp | 55 ++++++++++++++++ src/winextras/doc/src/qtwinextras-overview.qdoc | 17 +++-- src/winextras/qwintaskbarprogress.cpp | 72 +++++++++++++++++---- 8 files changed, 128 insertions(+), 16 deletions(-) create mode 100644 src/winextras/doc/images/taskbar-button.png create mode 100644 src/winextras/doc/images/taskbar-progress-indeterminate.png create mode 100644 src/winextras/doc/images/taskbar-progress-paused.png create mode 100644 src/winextras/doc/images/taskbar-progress-stopped.png create mode 100644 src/winextras/doc/images/taskbar-progress.png create mode 100644 src/winextras/doc/snippets/code/taskbar.cpp (limited to 'src') 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 Binary files /dev/null and b/src/winextras/doc/images/taskbar-button.png differ 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 Binary files /dev/null and b/src/winextras/doc/images/taskbar-progress-indeterminate.png differ 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 Binary files /dev/null and b/src/winextras/doc/images/taskbar-progress-paused.png differ 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 Binary files /dev/null and b/src/winextras/doc/images/taskbar-progress-stopped.png differ 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 Binary files /dev/null and b/src/winextras/doc/images/taskbar-progress.png differ 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 + +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() { -- cgit v1.2.3