source/modules/juce_gui_basics/windows/juce_ThreadWithProgressWindow.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 //==============================================================================
  30 /**
  31     A thread that automatically pops up a modal dialog box with a progress bar
  32     and cancel button while it's busy running.
  33
  34     These are handy for performing some sort of task while giving the user feedback
  35     about how long there is to go, etc.
  36
  37     E.g. @code
  38     class MyTask  : public ThreadWithProgressWindow
  39     {
  40     public:
  41         MyTask()    : ThreadWithProgressWindow ("busy...", true, true)
  42         {
  43         }
  44
  45         void run()
  46         {
  47             for (int i = 0; i < thingsToDo; ++i)
  48             {
  49                 // must check this as often as possible, because this is
  50                 // how we know if the user's pressed 'cancel'
  51                 if (threadShouldExit())
  52                     break;
  53
  54                 // this will update the progress bar on the dialog box
  55                 setProgress (i / (double) thingsToDo);
  56
  57
  58                 //   ... do the business here...
  59             }
  60         }
  61     };
  62
  63     void doTheTask()
  64     {
  65         MyTask m;
  66
  67         if (m.runThread())
  68         {
  69             // thread finished normally..
  70         }
  71         else
  72         {
  73             // user pressed the cancel button..
  74         }
  75     }
  76
  77     @endcode
  78
  79     @see Thread, AlertWindow
  80
  81     @tags{GUI}
  82 */
  83 class JUCE_API  ThreadWithProgressWindow  : public Thread,
  84                                             private Timer
  85 {
  86 public:
  87     //==============================================================================
  88     /** Creates the thread.
  89
  90         Initially, the dialog box won't be visible, it'll only appear when the
  91         runThread() method is called.
  92
  93         @param windowTitle              the title to go at the top of the dialog box
  94         @param hasProgressBar           whether the dialog box should have a progress bar (see
  95                                         setProgress() )
  96         @param hasCancelButton          whether the dialog box should have a cancel button
  97         @param timeOutMsWhenCancelling  when 'cancel' is pressed, this is how long to wait for
  98                                         the thread to stop before killing it forcibly (see
  99                                         Thread::stopThread() )
 100         @param cancelButtonText         the text that should be shown in the cancel button
 101                                         (if it has one). Leave this empty for the default "Cancel"
 102         @param componentToCentreAround  if this is non-null, the window will be positioned
 103                                         so that it's centred around this component.
 104     */
 105     ThreadWithProgressWindow (const String& windowTitle,
 106                               bool hasProgressBar,
 107                               bool hasCancelButton,
 108                               int timeOutMsWhenCancelling = 10000,
 109                               const String& cancelButtonText = String(),
 110                               Component* componentToCentreAround = nullptr);
 111
 112     /** Destructor. */
 113     ~ThreadWithProgressWindow() override;
 114
 115     //==============================================================================
 116    #if JUCE_MODAL_LOOPS_PERMITTED
 117     /** Starts the thread and waits for it to finish.
 118
 119         This will start the thread, make the dialog box appear, and wait until either
 120         the thread finishes normally, or until the cancel button is pressed.
 121
 122         Before returning, the dialog box will be hidden.
 123
 124         @param priority   the priority to use when starting the thread - see
 125                           Thread::startThread() for values
 126         @returns true if the thread finished normally; false if the user pressed cancel
 127     */
 128     bool runThread (int priority = 5);
 129    #endif
 130
 131     /** Starts the thread and returns.
 132
 133         This will start the thread and make the dialog box appear in a modal state. When
 134         the thread finishes normally, or the cancel button is pressed, the window will be
 135         hidden and the threadComplete() method will be called.
 136
 137         @param priority   the priority to use when starting the thread - see
 138                           Thread::startThread() for values
 139     */
 140     void launchThread (int priority = 5);
 141
 142     /** The thread should call this periodically to update the position of the progress bar.
 143
 144         @param newProgress  the progress, from 0.0 to 1.0
 145         @see setStatusMessage
 146     */
 147     void setProgress (double newProgress);
 148
 149     /** The thread can call this to change the message that's displayed in the dialog box. */
 150     void setStatusMessage (const String& newStatusMessage);
 151
 152     /** Returns the AlertWindow that is being used. */
 153     AlertWindow* getAlertWindow() const noexcept        { return alertWindow.get(); }
 154
 155     //==============================================================================
 156     /** This method is called (on the message thread) when the operation has finished.
 157         You may choose to use this callback to delete the ThreadWithProgressWindow object.
 158     */
 159     virtual void threadComplete (bool userPressedCancel);
 160
 161 private:
 162     //==============================================================================
 163     void timerCallback() override;
 164
 165     double progress;
 166     std::unique_ptr<AlertWindow> alertWindow;
 167     String message;
 168     CriticalSection messageLock;
 169     const int timeOutMsWhenCancelling;
 170     bool wasCancelledByUser;
 171
 172     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ThreadWithProgressWindow)
 173 };
 174
 175 } // namespace juce