interface/wx/progdlg.h

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