document wxProgressDialog::Update(maximumValue) behaviour and warn the user that it may generate unwanted re-entrancies because of wxDialog::ShowModal()

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

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().
 

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.

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