document wxProgressDialog::Update(maximumValue) behaviour and warn the user that...

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@59431 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/interface/wx/dialog.h b/interface/wx/dialog.h
index e53af26867d4c1815cef8e9253fdbc1f14a3a7ff..4cf131dd17e159ec0d5f324125a793756a97f7e9 100644 (file)
--- a/interface/wx/dialog.h
+++ b/interface/wx/dialog.h
@@ -586,6 +586,7 @@ public:
         Note that this function creates a temporary event loop which takes
         precedence over the application's main event loop (see wxEventLoopBase)
         and which is destroyed when the dialog is dismissed.
+        This also results in a call to wxApp::ProcessPendingEvents().
 
         @return The value set with SetReturnCode().
 

diff --git a/interface/wx/progdlg.h b/interface/wx/progdlg.h
index 963580e97b12c1b069dc530670ddf6cdb6257852..cbd51b5e4f35cbef605ab334016015b14854d422 100644 (file)
--- a/interface/wx/progdlg.h
+++ b/interface/wx/progdlg.h
@@ -28,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
@@ -130,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.

diff --git a/src/generic/progdlgg.cpp b/src/generic/progdlgg.cpp
index 224f40a593eff3943678d77b046625177adbd635..ca8f0d5d617ed41d3ee741c461edc5854fd064d5 100644 (file)
--- a/src/generic/progdlgg.cpp
+++ b/src/generic/progdlgg.cpp
@@ -411,6 +411,9 @@ wxProgressDialog::Update(int value, const wxString& newmsg, bool *skip)
             //       should be no side-effects
             wxEventLoopBase::GetActive()->YieldFor(wxEVT_CATEGORY_UI);
 
+            // NOTE: this call results in a new event loop being created
+            //       and to a call to ProcessPendingEvents() (which may generate
+            //       unwanted re-entrancies).
             (void)ShowModal();
         }
         else // auto hide