path: root/src/winextras/qwintaskbarprogress.cpp

/****************************************************************************
 **
 ** Copyright (C) 2013 Ivan Vizir <define-true-false@yandex.com>
 ** Contact: http://www.qt.io/licensing/
 **
 ** This file is part of the QtWinExtras module of the Qt Toolkit.
 **
 ** $QT_BEGIN_LICENSE:LGPL21$
 ** Commercial License Usage
 ** Licensees holding valid commercial Qt licenses may use this file in
 ** accordance with the commercial license agreement provided with the
 ** Software or, alternatively, in accordance with the terms contained in
 ** a written agreement between you and The Qt Company. For licensing terms
 ** and conditions see http://www.qt.io/terms-conditions. For further
 ** information use the contact form at http://www.qt.io/contact-us.
 **
 ** GNU Lesser General Public License Usage
 ** Alternatively, this file may be used under the terms of the GNU Lesser
 ** General Public License version 2.1 or version 3 as published by the Free
 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
 ** following information to ensure the GNU Lesser General Public License
 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 **
 ** As a special exception, The Qt Company gives you certain additional
 ** rights. These rights are described in The Qt Company LGPL Exception
 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
 **
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/

#include "qwintaskbarprogress.h"

QT_BEGIN_NAMESPACE

/*!
    \class QWinTaskbarProgress
    \inmodule QtWinExtras
    \brief The QWinTaskbarProgress class represents a progress indicator in the Windows taskbar.

    \since 5.2

    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::pausedChanged(bool paused)
    \internal (for QWinTaskbarButton and QML compatibility)
 */

/*!
    \fn void QWinTaskbarProgress::stoppedChanged(bool stopped)
    \internal (for QWinTaskbarButton and QML compatibility)
 */

class QWinTaskbarProgressPrivate
{
public:
    QWinTaskbarProgressPrivate();

    int value;
    int minimum;
    int maximum;
    bool visible;
    bool paused;
    bool stopped;
};

QWinTaskbarProgressPrivate::QWinTaskbarProgressPrivate() :
    value(0), minimum(0), maximum(100), visible(false), paused(false), stopped(false)
{
}

/*!
    Constructs a QWinTaskbarProgress with the parent object \a parent.
 */
QWinTaskbarProgress::QWinTaskbarProgress(QObject *parent) :
    QObject(parent), d_ptr(new QWinTaskbarProgressPrivate)
{
}

/*!
    Destroys the QWinTaskbarProgress.
 */
QWinTaskbarProgress::~QWinTaskbarProgress()
{
}

/*!
    \property QWinTaskbarProgress::value
    \brief the current value of the progress indicator

    The default value is \c 0.
 */
int QWinTaskbarProgress::value() const
{
    Q_D(const QWinTaskbarProgress);
    return d->value;
}

void QWinTaskbarProgress::setValue(int value)
{
    Q_D(QWinTaskbarProgress);
    if ((value == d->value) || value < d->minimum || value > d->maximum)
        return;

    d->value = value;
    emit valueChanged(d->value);
}

/*!
    \property QWinTaskbarProgress::minimum
    \brief the minimum value of the progress indicator

    The default value is \c 0.
 */
int QWinTaskbarProgress::minimum() const
{
    Q_D(const QWinTaskbarProgress);
    return d->minimum;
}

void QWinTaskbarProgress::setMinimum(int minimum)
{
    Q_D(QWinTaskbarProgress);
    setRange(minimum, qMax(minimum, d->maximum));
}

/*!
    \property QWinTaskbarProgress::maximum
    \brief the maximum value of the progress indicator

    The default value is \c 100.
 */
int QWinTaskbarProgress::maximum() const
{
    Q_D(const QWinTaskbarProgress);
    return d->maximum;
}

void QWinTaskbarProgress::setMaximum(int maximum)
{
    Q_D(QWinTaskbarProgress);
    setRange(qMin(d->minimum, maximum), maximum);
}

/*!
    \property QWinTaskbarProgress::visible
    \brief whether the progress indicator is visible.

    The default value is \c false.
 */
bool QWinTaskbarProgress::isVisible() const
{
    Q_D(const QWinTaskbarProgress);
    return d->visible;
}

void QWinTaskbarProgress::setVisible(bool visible)
{
    Q_D(QWinTaskbarProgress);
    if (visible == d->visible)
        return;

    d->visible = visible;
    emit visibilityChanged(d->visible);
}

/*!
    Shows the progress indicator.
 */
void QWinTaskbarProgress::show()
{
    setVisible(true);
}

/*!
    Hides the progress indicator.
 */
void QWinTaskbarProgress::hide()
{
    setVisible(false);
}

/*!
    Sets both the \a minimum and \a maximum values.
 */
void QWinTaskbarProgress::setRange(int minimum, int maximum)
{
    Q_D(QWinTaskbarProgress);
    const bool minChanged = minimum != d->minimum;
    const bool maxChanged = maximum != d->maximum;
    if (minChanged || maxChanged) {
        d->minimum = minimum;
        d->maximum = qMax(minimum, maximum);

        if (d->value < d->minimum || d->value > d->maximum)
            reset();

        if (minChanged)
            emit minimumChanged(d->minimum);
        if (maxChanged)
            emit maximumChanged(d->maximum);
    }
}

/*!
    Resets the progress indicator.

    This function rewinds the value to the minimum value.
 */
void QWinTaskbarProgress::reset()
{
    setValue(minimum());
}

/*!
    \property QWinTaskbarProgress::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
{
    Q_D(const QWinTaskbarProgress);
    return d->paused;
}

void QWinTaskbarProgress::setPaused(bool paused)
{
    Q_D(QWinTaskbarProgress);
    if (paused == d->paused || d->stopped)
        return;

    d->paused = paused;
    emit pausedChanged(d->paused);
}

/*!
    Pauses the progress indicator.

    \sa paused
 */
void QWinTaskbarProgress::pause()
{
    setPaused(true);
}

/*!
    Resumes a paused or stopped progress indicator.

    \sa paused, stopped
 */
void QWinTaskbarProgress::resume()
{
    Q_D(QWinTaskbarProgress);
    setPaused(false);
    if (d->stopped) {
        d->stopped = false;
        emit stoppedChanged(false);
    }
}

/*!
    \property QWinTaskbarProgress::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
{
    Q_D(const QWinTaskbarProgress);
    return d->stopped;
}

/*!
    Stops the progress indicator.

    \sa stopped
 */
void QWinTaskbarProgress::stop()
{
    Q_D(QWinTaskbarProgress);
    setPaused(false);
    if (!d->stopped) {
        d->stopped = true;
        emit stoppedChanged(true);
    }
}

QT_END_NAMESPACE