fix generation of wxEVT_CHAR_HOOK events which, incredibly, seems to have never worke...

[wxWidgets.git] / interface / wx / progdlg.h

diff --git a/interface/wx/progdlg.h b/interface/wx/progdlg.h
index 1c56dd98adc74c5ed0d0730cf353b3cb7973e9d6..cbd51b5e4f35cbef605ab334016015b14854d422 100644 (file)
--- a/interface/wx/progdlg.h
+++ b/interface/wx/progdlg.h
@@ -10,9 +10,16 @@
     @class wxProgressDialog
 
     This class represents a dialog that shows a short message and a
-    progress bar. Optionally, it can display ABORT and SKIP buttons,
+    progress bar. Optionally, it can display ABORT and SKIP buttons, and
     the elapsed, remaining and estimated time for the end of the progress.
 
+    Note that you must be aware that wxProgressDialog internally calls
+    wxEventLoopBase::YieldFor with @c wxEVT_CATEGORY_UI and @c wxEVT_CATEGORY_USER_INPUT
+    and this may cause unwanted re-entrancies or the out-of-order processing
+    of pending events (to help preventing the last problem if you're using
+    wxProgressDialog in a multi-threaded application you should be sure to use
+    wxThreadEvent for your inter-threads communications).
+
     @beginStyleTable
     @style{wxPD_APP_MODAL}
            Make the progress dialog modal. If this flag is not given, it is
@@ -21,8 +28,13 @@
     @style{wxPD_AUTO_HIDE}
            Causes the progress dialog to disappear from screen as soon as the
            maximum value of the progress meter has been reached.
+           If this style is not present, the dialog will become a modal dialog
+           (see wxDialog::ShowModal) once the maximum value has been reached;
+           this results in processing of pending events and may cause
+           unwanted re-entrancies.
     @style{wxPD_SMOOTH}
-           Causes smooth progress of the gauge control.
+           Causes smooth progress of the gauge control (uses a wxGauge with the
+           @c wxGA_SMOOTH style).
     @style{wxPD_CAN_ABORT}
            This flag tells the dialog that it should have a "Cancel" button
            which the user may press. If this happens, the next call to
@@ -57,6 +69,8 @@ public:
             Message displayed above the progress bar.
         @param maximum
             Maximum value for the progress bar.
+            In the generic implementation the progress bar is constructed
+            only if this value is greater than zero.
         @param parent
             Parent window.
         @param style
@@ -72,6 +86,31 @@ public:
     */
     virtual ~wxProgressDialog();
 
+    /**
+        Returns the last value passed to the Update() function or
+        @c wxNOT_FOUND if the dialog has no progress bar.
+
+        @since 2.9.0
+    */
+    int GetValue() const;
+
+    /**
+        Returns the maximum value of the progress meter, as passed to
+        the constructor or @c wxNOT_FOUND if the dialog has no progress bar.
+
+        @since 2.9.0
+    */
+    int GetRange() const;
+
+    /**
+        Returns the last message passed to the Update() function;
+        if you always passed wxEmptyString to Update() then the message
+        set through the constructor is returned.
+
+        @since 2.9.0
+    */
+    wxString GetMessage() const;
+
     /**
         Works like Update() but makes the gauge control run in indeterminate mode
         (see wxGauge documentation); sets the remaining and the estimated time labels
@@ -96,8 +135,9 @@ public:
 
         @param value
             The new value of the progress meter. It should be less than or equal to
-            the maximum value given to the constructor and the dialog is closed if
-            it is equal to the maximum.
+            the maximum value given to the constructor.
+            See @c wxPD_AUTO_HIDE style for more info about the behaviour of
+            wxProgressDialog when @a value is the maximum value given in the ctor.
         @param newmsg
             The new messages for the progress dialog text, if it is
             empty (which is the default) the message is not changed.
@@ -105,7 +145,7 @@ public:
             If "Skip" button was pressed since last Update() call,
             this is set to @true.
     */
-    virtual bool Update(int value, const wxString& newmsg = "",
+    virtual bool Update(int value, const wxString& newmsg = wxEmptyString,
                         bool* skip = NULL);
 };