src/Utils/MiscUI/SysProgressDlg.h

   1 // TortoiseGit - a Windows shell extension for easy version control
   2
   3 // Copyright (C) 2009, 2011-2012, 2016-2017, 2021, 2023 - TortoiseGit
   4 // Copyright (C) 2003-2011, 2015 - TortoiseSVN
   5
   6 // This program is free software; you can redistribute it and/or
   7 // modify it under the terms of the GNU General Public License
   8 // as published by the Free Software Foundation; either version 2
   9 // of the License, or (at your option) any later version.
  10
  11 // This program is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15
  16 // You should have received a copy of the GNU General Public License
  17 // along with this program; if not, write to the Free Software Foundation,
  18 // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  19 //
  20 #pragma once
  21
  22 /**
  23  * \ingroup Utils
  24  * A wrapper class for the IProgressDialog interface. Thats
  25  * the dialog used by the shell/IE to show progress in e.g.
  26  * copying, downloading, ...
  27  *
  28  * \remark you need to call AfxOleInit() before using this class, preferably in
  29  * your app's InitInistance() method.
  30  */
  31 class CSysProgressDlg
  32 {
  33 public:
  34         CSysProgressDlg();
  35         ~CSysProgressDlg();
  36
  37         /**
  38          * sets the title of the progress dialog box.
  39          * \param szTitle pointer to a nullptr-terminated string that contains the dialog box title
  40          */
  41         void SetTitle(LPCWSTR szTitle);
  42         /**
  43         * sets the title of the progress dialog box to a string resource value.
  44         */
  45         void SetTitle ( UINT idTitle);
  46
  47         /**
  48          * Displays a message.
  49          * \param dwLine line number on which the text is to be displayed. There are three lines possible, two lines if SetCalculateTime() is set to true.
  50          * \param szText nullptr-terminated string that contains the line text.
  51          * \param bCompactPath set to true if you want the text to be compacted (if it is a path) to fit on the line.
  52          *
  53          * \remark This call should be made *after* the dialog has been shown - this allows
  54          * the system to measure the space available for the text, and do path compaction properly
  55          */
  56         void SetLine(DWORD dwLine, LPCWSTR szText, bool bCompactPath = false);
  57
  58 #ifdef _MFC_VER
  59         /**
  60         * Wrappers around set line, to do a CString::Format type operation
  61         * See SetLine for more details
  62         *
  63         * \remark These calls should be made *after* the dialog has been shown - this allows
  64         * the system to measure the space available for the text, and do path compaction properly
  65         */
  66         void FormatPathLine ( DWORD dwLine, UINT idFormatText, ...);
  67         void FormatPathLine(DWORD dwLine, LPCWSTR FormatText, ...);
  68         void FormatNonPathLine ( DWORD dwLine, UINT idFormatText, ...);
  69         void FormatNonPathLine(DWORD dwLine, LPCWSTR FormatText, ...);
  70 #endif
  71         /**
  72          * Sets a message to be displayed if the user clicks the cancel button.
  73          * \param szMessage pointer to a nullptr-terminated string that contains the message.
  74          * \remark Even though the user clicks Cancel, the application cannot immediately
  75          * call Stop() to close the dialog box. The application
  76          * must wait until the next time it calls HasUserCancelled() to
  77          * discover that the user has canceled the operation. Since this delay might be
  78          * significant, the progress dialog box provides the user with immediate feedback
  79          * by clearing text lines 1 and 2 and displaying the cancel message on line 3.
  80          * The message is intended to let the user know that the delay is normal and that
  81          * the progress dialog box will be closed shortly. It is typically is set to
  82          * something like "Please wait while ...".
  83          */
  84         void SetCancelMsg(LPCWSTR szMessage);
  85 #ifdef _MFC_VER
  86         void SetCancelMsg ( UINT idMessage );
  87 #endif
  88
  89         /**
  90          * Specifies that the progress dialog should have a line indicating the time remaining to complete.
  91          * \param bCalculate false to deactivate the time remaining line.
  92          */
  93         void SetTime ( bool bTime = true );
  94
  95         /**
  96          * Specifies if the progress bar should be shown or not.
  97          */
  98         void SetShowProgressBar ( bool bShow = true );
  99
 100         /**
 101          * Resets the progress dialog box timer to zero.
 102          * \remark the timer is used to estimate the remaining time. It is started when your
 103          * application calls ShowModal() or ShowModeless(). Unless your application will
 104          * start immediately, it should call ResetTimer() just before starting the operation.
 105          * This practice ensures that the time estimates will be as accurate as possible.
 106          * This method should not be called after the first call to UpdateProgress().
 107          */
 108         void ResetTimer();
 109
 110         /**
 111          * Shows the progress dialog box modal.
 112          */
 113 #ifdef _MFC_VER
 114         HRESULT ShowModal ( CWnd* pwndParent, BOOL immediately = true );
 115 #endif
 116         HRESULT ShowModal ( HWND hWndParent, BOOL immediately = true );
 117         /**
 118          * Shows the progress dialog box modeless.
 119          */
 120 #ifdef _MFC_VER
 121         HRESULT ShowModeless ( CWnd* pwndParent, BOOL immediately = true );
 122 #endif
 123         HRESULT ShowModeless ( HWND hWndParent, BOOL immediately = true );
 124
 125         /**
 126          * Stops the progress dialog box and removes it from the screen.
 127          */
 128         void Stop();
 129
 130         /**
 131          * Updates the progress dialog box with the current state of the operation.
 132          * \param dwProgress Application-defined value that indicates what proportion of the operation has been completed at the time the method was called
 133          * \param dwMax Application-defined value that specifies what value dwCompleted will have when the operation is complete
 134          */
 135         void SetProgress ( DWORD dwProgress, DWORD dwMax );
 136         /**
 137          * Updates the progress dialog box with the current state of the operation.
 138          * \param u64Progress Application-defined value that indicates what proportion of the operation has been completed at the time the method was called
 139          * \param u64ProgressMax Application-defined value that specifies what value dwCompleted will have when the operation is complete
 140          */
 141         void SetProgress64 ( ULONGLONG u64Progress, ULONGLONG u64ProgressMax );
 142
 143         /**
 144          * Checks whether the user has canceled the operation.
 145          */
 146         bool HasUserCancelled();
 147
 148         /**
 149          * Checks whether this object was created successfully. If the return value is false then
 150          * you MUST NOT use the current instance of this class.
 151          */
 152         bool IsValid() const { return m_pIDlg != nullptr; }
 153
 154         /**
 155          * Checks whether the window is shown.
 156          */
 157         bool IsVisible() const { return m_isVisible; }
 158
 159         /**
 160          * After a call to Stop() to hide the progress dialog,
 161          * call EnsureValid() to recreate the dialog and fill in the
 162          * data again.
 163          */
 164         bool EnsureValid();
 165
 166 protected:
 167         ATL::CComPtr<IProgressDialog> m_pIDlg;
 168         bool                            m_isVisible = false;
 169         DWORD                           m_dwDlgFlags = PROGDLG_NORMAL;
 170         HWND m_hWndProgDlg = nullptr;
 171         HWND m_hWndParent = nullptr;
 172         HWND m_hWndFocus = nullptr;
 173 };