QCustomProgressbar.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------------
Copyright (c) 2019, NDEVR LLC
tyler.parke@ndevr.org
  __    __   ____     _____ __     __  _______
 |  \  |  | |  __ \  |  ___|\ \   / / |   __  \
 |   \ |  | | |  \ \ | |___  \ \ / /  |  |__)  |
 |  . \|  | | |__/ / | |___   \ V /   |   _   /
 |  |\    |_|_____/__|_____|___\_/____|  | \  \
 |__| \__________________________________|  \__\
 
Subject to the terms of the Enterprise+ Agreement, NDEVR hereby grants 
Licensee a limited, non-exclusive, non-transferable, royalty-free license 
(without the right to sublicense) to use the API solely for the purpose of 
Licensee's internal development efforts to develop applications for which 
the API was provided.
 
The above copyright notice and this permission notice shall be included in all 
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
 
Library: Widgets
File: QCustomProgressbar
Included in API: True
Author(s): Tyler Parke
 *-----------------------------------------------------------------------------------------**/
#pragma once
#include "DLLInfo.h"
#include <NDEVR/BaseValues.h>
#include <NDEVR/TimeSpan.h>
#include <NDEVR/RGBColor.h>
#include <NDEVR/Buffer.h>
#include <QProgressBar>
namespace NDEVR
{
    class TranslatedString;
    class String;
    /**--------------------------------------------------------------------------------------------------
    \brief Allows for showing of progress bar in horizontal format. Defaults to look and feel of system progress
        bar.
 
    A progress bar 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 bar uses the concept of percent from 0.0 to 1.0. It will display the percentage 
        specified or can be set to an indeterminate or "spinning" state to indicate progress is 
        occuring, but at an unknown rate.
     *-----------------------------------------------------------------------------------------------**/
    class NDEVR_WIDGETS_API QCustomProgressBar : public QProgressBar
    {
        Q_OBJECT
    public:
        explicit QCustomProgressBar(QWidget* parent = nullptr);
        virtual ~QCustomProgressBar() override;
 
        /**--------------------------------------------------------------------------------------------------
                Parameters:
        color - The color to use as the progress bar
         *-----------------------------------------------------------------------------------------------**/
        void setProgressColor(RGBColor color);
 
        /**--------------------------------------------------------------------------------------------------
                called multiple times to form a gradiant.
        Parameters:
        percent -   The percent where this color will be most prominant.
        color -     The color use at the given percent
         *-----------------------------------------------------------------------------------------------**/
        void addProgressColor(fltp08 percent, RGBColor color);
 
        /**--------------------------------------------------------------------------------------------------
                Parameters:
        colors -    The colors to use. Will be evenly spaced out across progress.
         *-----------------------------------------------------------------------------------------------**/
        void setProgressColors(const Buffer<RGBColor>& colors);
        void clearProgressColors();
 
        /**--------------------------------------------------------------------------------------------------
                percent -   The percent that the progress bar is between 0.0 and 1.0. Invalid will set the value to 
                    indeterminate or "spinning" state
         *-----------------------------------------------------------------------------------------------**/
        virtual void setPercent(fltp08 percent);
        [[nodiscard]] fltp08 percent() const;
 
        /**--------------------------------------------------------------------------------------------------
                 *-----------------------------------------------------------------------------------------------**/
        [[nodiscard]] bool isIndeterminateState() const;
 
        /**--------------------------------------------------------------------------------------------------
        
        Parameters:
        draw_background - Whether or not to draw the background
         *-----------------------------------------------------------------------------------------------**/
        void setDrawBackground(bool draw_background);
 
        /**--------------------------------------------------------------------------------------------------
                if progress is indeterminate. Translated version of setFormat.
 
        Parameters:
        message -   The message to display inside the progress widget
         *-----------------------------------------------------------------------------------------------**/
        virtual void setMessage(const TranslatedString& message);
 
        /**--------------------------------------------------------------------------------------------------
                if progress is indeterminate. Untranslated version of setMessage.
 
        Parameters:
        message -   The message to display inside the progress widget
         *-----------------------------------------------------------------------------------------------**/
        void setFormat(const String& format);
 
        /**--------------------------------------------------------------------------------------------------
                an animation to indicate something is happening, but that a percent could not be determined.
        Can also be triggered by setPercent using Invalid to make indeterminate or a real number to make progress.
        Parameters:
        is_indeterminate -  whether to make the progress bar indeterminate
         *-----------------------------------------------------------------------------------------------**/
        virtual void setToIndeterminateState(bool is_indeterminate);
 
        /**--------------------------------------------------------------------------------------------------
        
        Parameters:
        span -      The span of time between a complete rotation or color animation when the widget is
                    set to indeterminate progress
         *-----------------------------------------------------------------------------------------------**/
        virtual void setIndeterminateAnimationTimespan(const TimeSpan& span);
    protected:
        [[nodiscard]] QSize sizeHint() const override;
        [[nodiscard]] QSize minimumSizeHint() const override;
        [[nodiscard]] fltp08 indeterminatePercent() const;
        [[nodiscard]] QString customText() const;
        void paintEvent(QPaintEvent* event) override;
    protected slots:
        void updateFromTimer();
    protected:
        void updateProgressColor();
    protected:
        QTimer* m_update_timer;
        TimeSpan m_indeterminate_period = TimeSpan(1.0);//how much time to do full cycle indeterminate animation
        Buffer<std::pair<fltp08, RGBColor>> m_progress_colors;
        QString m_last_text;
        bool m_draw_background;
    };
}