Make storing non-trivial data in wxThreadSpecificInfo possible.

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

diff --git a/interface/wx/dialog.h b/interface/wx/dialog.h
index 3407302fcd32ff23082244120a8ead77b4040b27..b578adb6d1ce97f453d650ab6f2d5242ac4911b5 100644 (file)
--- a/interface/wx/dialog.h
+++ b/interface/wx/dialog.h
@@ -2,7 +2,6 @@
 // Name:        dialog.h
 // Purpose:     interface of wxDialog
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
@@ -597,7 +596,8 @@ public:
 
         @return The value set with SetReturnCode().
 
-        @see ShowWindowModal(), EndModal(), GetReturnCode(), SetReturnCode()
+        @see ShowWindowModal(), ShowWindowModalThenDo(),
+             EndModal(), GetReturnCode(), SetReturnCode()
     */
     virtual int ShowModal();
 
@@ -608,15 +608,58 @@ public:
         user from interacting with their parent frame only but not with the
         rest of the application. They also don't block the program execution
         but instead return immediately, as Show(), and generate a
-        wxEVT_WINDOW_MODAL_DIALOG_CLOSED event later when the dialog is closed.
+        wxEVT_WINDOW_MODAL_DIALOG_CLOSED event (wxWindowModalDialogEvent)
+        later when the dialog is closed.
 
         Currently this function is only fully implemented in wxOSX ports, under
         the other platforms it behaves like ShowModal() (but also sends the
         above mentioned event).
 
+        @see wxWindowModalDialogEvent, ShowWindowModalThenDo()
+
         @since 2.9.0
      */
     void ShowWindowModal();
+
+    /**
+        Shows a dialog modal to the parent top level window only and call a
+        functor after the dialog is closed.
+
+        Same as the other ShowWindowModal() overload, but calls the functor
+        passed as the argument upon completion, instead of generating the
+        wxEVT_WINDOW_MODAL_DIALOG_CLOSED event.
+
+        This form is particularly useful in combination with C++11 lambdas,
+        when it allows writing window-modal very similarly to how ShowModal()
+        is used (with the notable exception of not being able to create
+        the dialog on stack):
+
+        @code
+        wxWindowPtr<wxDialog> dlg(new wxMessageDialog(this, "Hello!"));
+
+        dlg->ShowWindowModalThenDo([this,dlg](int retcode){
+            if ( retcode == wxID_OK )
+                DoSomething();
+            // dlg is implicitly destroyed here, because the pointer was
+            // explicitly captured by the lambda
+        });
+        @endcode
+
+        @param onEndModal  Function object to call when the dialog is
+                           closed. The functor is called with a single
+                           integer argument, dialog's return code.
+
+        @note The dialog instance must not be destroyed until @a onEndModal
+              is called. The best way to ensure thay is to use wxWindowPtr
+              to hold a pointer and include it in the lambda's capture,
+              by value (not reference!), as shown in the example above.
+
+        @since 3.0
+
+        @see wxWindowPtr<T>
+     */
+    template<typename Functor>
+    void ShowWindowModalThenDo(const Functor& onEndModal);
 };
 
 
@@ -660,12 +703,23 @@ public:
 };
 
 
+/**
+    Event sent by wxDialog::ShowWindowModal() when the dialog closes.
+
+    @since 2.9.0
+ */
 class wxWindowModalDialogEvent  : public wxCommandEvent
 {
 public:
+    /// Constructor
     wxWindowModalDialogEvent (wxEventType commandType = wxEVT_NULL, int id = 0);
 
+    /// Return the corresponding dialog.
     wxDialog *GetDialog() const;
+
+    /// Return the dialog's return code.
     int GetReturnCode() const;
+
+    /// Clone the event.
     virtual wxEvent *Clone() const;
 };