src/Utils/MiscUI/ProgressDlg.h

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