interface/wx/progdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        progdlg.h
   3 // Purpose:     interface of wxProgressDialog
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 #define wxPD_CAN_ABORT          0x0001
   9 #define wxPD_APP_MODAL          0x0002
  10 #define wxPD_AUTO_HIDE          0x0004
  11 #define wxPD_ELAPSED_TIME       0x0008
  12 #define wxPD_ESTIMATED_TIME     0x0010
  13 #define wxPD_SMOOTH             0x0020
  14 #define wxPD_REMAINING_TIME     0x0040
  15 #define wxPD_CAN_SKIP           0x0080
  16
  17 /**
  18     @class wxGenericProgressDialog
  19
  20     This class represents a dialog that shows a short message and a
  21     progress bar. Optionally, it can display ABORT and SKIP buttons, and
  22     the elapsed, remaining and estimated time for the end of the progress.
  23
  24     This class provides a generic implementation of the progress dialog.  If
  25     the platform has a native progress dialog available then it will be
  26     accessible using the @a wxProgressDialog class, otherwise it will
  27     essentially be the same as this class.
  28
  29     Note that you must be aware that wxProgressDialog internally calls
  30     wxEventLoopBase::YieldFor with @c wxEVT_CATEGORY_UI and @c wxEVT_CATEGORY_USER_INPUT
  31     and this may cause unwanted re-entrancies or the out-of-order processing
  32     of pending events (to help preventing the last problem if you're using
  33     wxProgressDialog in a multi-threaded application you should be sure to use
  34     wxThreadEvent for your inter-threads communications).
  35
  36     @beginStyleTable
  37     @style{wxPD_APP_MODAL}
  38            Make the progress dialog modal. If this flag is not given, it is
  39            only "locally" modal - that is the input to the parent window is
  40            disabled, but not to the other ones.
  41     @style{wxPD_AUTO_HIDE}
  42            Causes the progress dialog to disappear from screen as soon as the
  43            maximum value of the progress meter has been reached.
  44            If this style is not present, the dialog will become a modal dialog
  45            (see wxDialog::ShowModal) once the maximum value has been reached
  46            and wait for the user to dismiss it.
  47     @style{wxPD_SMOOTH}
  48            Causes smooth progress of the gauge control (uses a wxGauge with the
  49            @c wxGA_SMOOTH style).
  50     @style{wxPD_CAN_ABORT}
  51            This flag tells the dialog that it should have a "Cancel" button
  52            which the user may press. If this happens, the next call to
  53            Update() will return @false.
  54     @style{wxPD_CAN_SKIP}
  55            This flag tells the dialog that it should have a "Skip" button
  56            which the user may press. If this happens, the next call to
  57            Update() will return @true in its skip parameter.
  58     @style{wxPD_ELAPSED_TIME}
  59            This flag tells the dialog that it should show elapsed time (since
  60            creating the dialog).
  61     @style{wxPD_ESTIMATED_TIME}
  62            This flag tells the dialog that it should show estimated time.
  63     @style{wxPD_REMAINING_TIME}
  64            This flag tells the dialog that it should show remaining time.
  65     @endStyleTable
  66
  67     @library{wxcore}
  68     @category{cmndlg}
  69 */
  70 class wxGenericProgressDialog : public wxDialog
  71 {
  72 public:
  73     /**
  74         Constructor. Creates the dialog, displays it and disables user input
  75         for other windows, or, if @c wxPD_APP_MODAL flag is not given, for its
  76         parent window only.
  77
  78         @param title
  79             Dialog title to show in titlebar.
  80         @param message
  81             Message displayed above the progress bar.
  82         @param maximum
  83             Maximum value for the progress bar.
  84             In the generic implementation the progress bar is constructed
  85             only if this value is greater than zero.
  86         @param parent
  87             Parent window.
  88         @param style
  89             The dialog style. See wxProgressDialog.
  90     */
  91     wxGenericProgressDialog(const wxString& title, const wxString& message,
  92                             int maximum = 100,
  93                             wxWindow* parent = NULL,
  94                             int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL);
  95
  96     /**
  97         Destructor. Deletes the dialog and enables all top level windows.
  98     */
  99     virtual ~wxGenericProgressDialog();
 100
 101     /**
 102         Returns the last value passed to the Update() function or
 103         @c wxNOT_FOUND if the dialog has no progress bar.
 104
 105         @since 2.9.0
 106     */
 107     int GetValue() const;
 108
 109     /**
 110         Returns the maximum value of the progress meter, as passed to
 111         the constructor or @c wxNOT_FOUND if the dialog has no progress bar.
 112
 113         @since 2.9.0
 114     */
 115     int GetRange() const;
 116
 117     /**
 118         Returns the last message passed to the Update() function;
 119         if you always passed wxEmptyString to Update() then the message
 120         set through the constructor is returned.
 121
 122         @since 2.9.0
 123     */
 124     wxString GetMessage() const;
 125
 126     /**
 127         Like Update() but makes the gauge control run in indeterminate mode.
 128
 129         In indeterminate mode the remaining and the estimated time labels (if
 130         present) are set to "Unknown" or to @a newmsg (if it's non-empty).
 131         Each call to this function moves the progress bar a bit to indicate
 132         that some progress was done.
 133
 134         @see wxGauge::Pulse(), Update()
 135     */
 136     virtual bool Pulse(const wxString& newmsg = wxEmptyString, bool* skip = NULL);
 137
 138     /**
 139         Can be used to continue with the dialog, after the user had clicked the "Abort" button.
 140     */
 141     void Resume();
 142
 143     /**
 144         Changes the maximum value of the progress meter given in the constructor.
 145         This function can only be called (with a positive value) if the value passed
 146         in the constructor was positive.
 147
 148         @since 2.9.1
 149     */
 150     void SetRange(int maximum);
 151
 152
 153       /**
 154          Returns true if the "Cancel" button was pressed.
 155
 156          Normally a Cancel button press is indicated by Update() returning
 157          @false but sometimes it may be more convenient to check if the dialog
 158          was cancelled from elsewhere in the code and this function allows to
 159          do it.
 160
 161          It always returns @false if the Cancel button is not shown at all.
 162
 163          @since 2.9.1
 164      */
 165     bool WasCancelled() const;
 166
 167      /**
 168          Returns true if the "Skip" button was pressed.
 169
 170          This is similar to WasCancelled() but returns @true if the "Skip"
 171          button was pressed, not the "Cancel" one.
 172
 173          @since 2.9.1
 174      */
 175     bool WasSkipped() const;
 176
 177
 178     /**
 179         Updates the dialog, setting the progress bar to the new value and
 180         updating the message if new one is specified.
 181
 182         Returns @true unless the "Cancel" button has been pressed.
 183
 184         If @false is returned, the application can either immediately destroy the
 185         dialog or ask the user for the confirmation and if the abort is not confirmed
 186         the dialog may be resumed with Resume() function.
 187
 188         If @a value is the maximum value for the dialog, the behaviour of the
 189         function depends on whether @c wxPD_AUTO_HIDE was used when the dialog
 190         was created. If it was, the dialog is hidden and the function returns
 191         immediately. If it was not, the dialog becomes a modal dialog and waits
 192         for the user to dismiss it, meaning that this function does not return
 193         until this happens.
 194
 195         Notice that you may want to call Fit() to change the dialog size to
 196         conform to the length of the new message if desired. The dialog does
 197         not do this automatically.
 198
 199         @param value
 200             The new value of the progress meter. It should be less than or equal to
 201             the maximum value given to the constructor.
 202         @param newmsg
 203             The new messages for the progress dialog text, if it is
 204             empty (which is the default) the message is not changed.
 205         @param skip
 206             If "Skip" button was pressed since last Update() call,
 207             this is set to @true.
 208     */
 209     virtual bool Update(int value, const wxString& newmsg = wxEmptyString,
 210                         bool* skip = NULL);
 211 };
 212
 213
 214
 215
 216 /**
 217     @class wxProgressDialog
 218
 219     If supported by the platform this class will provide the platform's native
 220     progress dialog, else it will simply be the @a wxGenericProgressDialog.
 221 */
 222 class wxProgressDialog : public wxGenericProgressDialog
 223 {
 224 public:
 225     wxProgressDialog( const wxString& title, const wxString& message,
 226                       int maximum = 100,
 227                       wxWindow *parent = NULL,
 228                       int style = wxPD_APP_MODAL | wxPD_AUTO_HIDE );
 229 };