src/Utils/MiscUI/SysProgressDlg.h

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