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 e057bc30ed6a2cc65f40bdc2d1085f17012efca2..b578adb6d1ce97f453d650ab6f2d5242ac4911b5 100644 (file)
--- a/interface/wx/dialog.h
+++ b/interface/wx/dialog.h
@@ -2,8 +2,7 @@
 // Name:        dialog.h
 // Purpose:     interface of wxDialog
 // Author:      wxWidgets team
 // Name:        dialog.h
 // Purpose:     interface of wxDialog
 // Author:      wxWidgets team

-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -16,6 +15,16 @@ enum wxDialogLayoutAdaptationMode
     wxDIALOG_ADAPTATION_MODE_DISABLED = 2   ///< Disable this dialog overriding global status.
 };
 
     wxDIALOG_ADAPTATION_MODE_DISABLED = 2   ///< Disable this dialog overriding global status.
 };
 

+#define wxDIALOG_NO_PARENT      0x00000020  ///< Don't make owned by apps top window
+
+#define wxDEFAULT_DIALOG_STYLE  (wxCAPTION | wxSYSTEM_MENU | wxCLOSE_BOX)
+
+
+#define wxDIALOG_ADAPTATION_NONE             0  ///< Don't do any layout adaptation
+#define wxDIALOG_ADAPTATION_STANDARD_SIZER   1  ///< Only look for wxStdDialogButtonSizer for non-scrolling part
+#define wxDIALOG_ADAPTATION_ANY_SIZER        2  ///< Also look for any suitable sizer for non-scrolling part
+#define wxDIALOG_ADAPTATION_LOOSE_BUTTONS    3  ///< Also look for 'loose' standard buttons for non-scrolling part
+

 /**
     @class wxDialog
 
 /**
     @class wxDialog
 


@@ -88,7 +97,7 @@ enum wxDialogLayoutAdaptationMode
            Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and
            wxSYSTEM_MENU (the last one is not used under Unix).
     @style{wxRESIZE_BORDER}
            Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and
            wxSYSTEM_MENU (the last one is not used under Unix).
     @style{wxRESIZE_BORDER}

-           Display a resizeable frame around the window.
+           Display a resizable frame around the window.

     @style{wxSYSTEM_MENU}
            Display a system menu.
     @style{wxCLOSE_BOX}
     @style{wxSYSTEM_MENU}
            Display a system menu.
     @style{wxCLOSE_BOX}


@@ -102,8 +111,8 @@ enum wxDialogLayoutAdaptationMode
     @style{wxSTAY_ON_TOP}
            The dialog stays on top of all other windows.
     @style{wxNO_3D}
     @style{wxSTAY_ON_TOP}
            The dialog stays on top of all other windows.
     @style{wxNO_3D}

-           Under Windows, specifies that the child controls should not have 3D
-           borders unless specified in the control.
+           This style is obsolete and doesn't do anything any more, don't use
+           it in any new code.

     @style{wxDIALOG_NO_PARENT}
            By default, a dialog created with a @NULL parent window will be
            given the @ref wxApp::GetTopWindow() "application's top level window"
     @style{wxDIALOG_NO_PARENT}
            By default, a dialog created with a @NULL parent window will be
            given the @ref wxApp::GetTopWindow() "application's top level window"


@@ -112,7 +121,7 @@ enum wxDialogLayoutAdaptationMode
     @style{wxDIALOG_EX_CONTEXTHELP}
            Under Windows, puts a query button on the caption. When pressed,
            Windows will go into a context-sensitive help mode and wxWidgets
     @style{wxDIALOG_EX_CONTEXTHELP}
            Under Windows, puts a query button on the caption. When pressed,
            Windows will go into a context-sensitive help mode and wxWidgets

-           will send a wxEVT_HELP event if the user clicked on an application
+           will send a @c wxEVT_HELP event if the user clicked on an application

            window. Note that this is an extended style and must be set by
            calling SetExtraStyle() before Create is called (two-step
            construction).
            window. Note that this is an extended style and must be set by
            calling SetExtraStyle() before Create is called (two-step
            construction).


@@ -126,13 +135,15 @@ enum wxDialogLayoutAdaptationMode
     styles to have an effect.
 
 
     styles to have an effect.
 
 

-    @beginEventTable{wxCloseEvent}
+    @beginEventEmissionTable{wxCloseEvent}

     @event{EVT_CLOSE(func)}
         The dialog is being closed by the user or programmatically (see wxWindow::Close).
         The user may generate this event clicking the close button
         (typically the 'X' on the top-right of the title bar) if it's present
         (see the @c wxCLOSE_BOX style) or by clicking a button with the
         @c wxID_CANCEL or @c wxID_OK ids.
     @event{EVT_CLOSE(func)}
         The dialog is being closed by the user or programmatically (see wxWindow::Close).
         The user may generate this event clicking the close button
         (typically the 'X' on the top-right of the title bar) if it's present
         (see the @c wxCLOSE_BOX style) or by clicking a button with the
         @c wxID_CANCEL or @c wxID_OK ids.

+    @event{EVT_INIT_DIALOG(func)}
+        Process a @c wxEVT_INIT_DIALOG event. See wxInitDialogEvent.

     @endEventTable
 
     @library{wxcore}
     @endEventTable
 
     @library{wxcore}


@@ -246,9 +257,30 @@ public:
 
         @note Just like CreateButtonSizer(), this function may return @NULL if
               no buttons were created.
 
         @note Just like CreateButtonSizer(), this function may return @NULL if
               no buttons were created.

+
+        This is a combination of CreateButtonSizer() and
+        CreateSeparatedSizer().

     */
     wxSizer* CreateSeparatedButtonSizer(long flags);
 
     */
     wxSizer* CreateSeparatedButtonSizer(long flags);
 

+    /**
+        Returns the sizer containing the given one with a separating
+        wxStaticLine if necessarily.
+
+        This function is useful for creating the sizer containing footer-like
+        contents in dialog boxes. It will add a separating static line only if
+        it conforms to the current platform convention (currently it is not
+        added under Mac where the use of static lines for grouping is
+        discouraged and is added elsewhere).
+
+        @since 2.9.2
+
+        @param sizer The sizer to wrap, must be non-@NULL.
+        @return The sizer wrapping the input one or possibly the input sizer
+            itself if no wrapping is necessary.
+     */
+    wxSizer *CreateSeparatedSizer(wxSizer *sizer);
+

     /**
         Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a
         bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY,
     /**
         Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a
         bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY,


@@ -258,6 +290,12 @@ public:
     */
     wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags);
 
     */
     wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags);
 

+    /**
+       Splits text up at newlines and places the lines into wxStaticText
+       objects in a vertical wxBoxSizer.
+    */
+    wxSizer *CreateTextSizer( const wxString& message );
+

     /**
         Performs layout adaptation, usually if the dialog is too large to fit
         on the display.
     /**
         Performs layout adaptation, usually if the dialog is too large to fit
         on the display.


@@ -428,28 +466,11 @@ public:
     */
     virtual bool IsModal() const;
 
     */
     virtual bool IsModal() const;
 

-    /**
-        The default handler for wxEVT_SYS_COLOUR_CHANGED.
-
-        @param event
-            The colour change event.
-
-        @remarks Changes the dialog's colour to conform to the current settings
-                 (Windows only). Add an event table entry for your dialog class
-                 if you wish the behaviour to be different (such as keeping a
-                 user-defined background colour). If you do override this
-                 function, call wxEvent::Skip() to propagate the notification
-                 to child windows and controls.
-
-        @see wxSysColourChangedEvent
-    */
-    void OnSysColourChanged(wxSysColourChangedEvent& event);
-

     /**
         Sets the identifier to be used as OK button. When the button with this
         identifier is pressed, the dialog calls wxWindow::Validate() and
         wxWindow::TransferDataFromWindow() and, if they both return @true,
     /**
         Sets the identifier to be used as OK button. When the button with this
         identifier is pressed, the dialog calls wxWindow::Validate() and
         wxWindow::TransferDataFromWindow() and, if they both return @true,

-        closes the dialog with wxID_OK return code.
+        closes the dialog with the affirmative id return code.

 
         Also, when the user presses a hardware OK button on the devices having
         one or the special OK button in the PocketPC title bar, an event with
 
         Also, when the user presses a hardware OK button on the devices having
         one or the special OK button in the PocketPC title bar, an event with


@@ -532,19 +553,6 @@ public:
     */
     static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter);
 
     */
     static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter);
 

-    /**
-        @deprecated This function doesn't work for all ports, just use
-                    ShowModal() to show a modal dialog instead.
-
-        Allows the programmer to specify whether the dialog box is modal
-        (Show() blocks control until the dialog is hidden) or modeless (control
-        returns immediately).
-
-        @param flag
-            If @true, the dialog will be modal, otherwise it will be modeless.
-    */
-    void SetModal(bool flag);
-

     /**
         Sets the return code for this window.
 
     /**
         Sets the return code for this window.
 


@@ -571,7 +579,7 @@ public:
     virtual bool Show(bool show = 1);
 
     /**
     virtual bool Show(bool show = 1);
 
     /**

-        Shows a modal dialog.
+        Shows an application-modal dialog.

 
         Program flow does not return until the dialog has been dismissed with
         EndModal().
 
         Program flow does not return until the dialog has been dismissed with
         EndModal().


@@ -581,11 +589,77 @@ public:
         modeless dialog modal. However ShowModal() can't be called twice
         without intervening EndModal() calls.
 
         modeless dialog modal. However ShowModal() can't be called twice
         without intervening EndModal() calls.
 

+        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().
 
         @return The value set with SetReturnCode().
 

-        @see EndModal(), GetReturnCode(), SetReturnCode()
+        @see ShowWindowModal(), ShowWindowModalThenDo(),
+             EndModal(), GetReturnCode(), SetReturnCode()

     */
     virtual int ShowModal();
     */
     virtual int ShowModal();

+
+    /**
+        Shows a dialog modal to the parent top level window only.
+
+        Unlike ShowModal(), dialogs shown with this function only prevent the
+        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 (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);

 };
 
 
 };
 
 


@@ -593,7 +667,7 @@ public:
 /**
     @class wxDialogLayoutAdapter
 
 /**
     @class wxDialogLayoutAdapter
 

-    This abstract class is the base for classes that help wxWidgets peform
+    This abstract class is the base for classes that help wxWidgets perform

     run-time layout adaptation of dialogs. Principally, this is to cater for
     small displays by making part of the dialog scroll, but the application
     developer may find other uses for layout adaption.
     run-time layout adaptation of dialogs. Principally, this is to cater for
     small displays by making part of the dialog scroll, but the application
     developer may find other uses for layout adaption.


@@ -628,3 +702,24 @@ public:
     virtual bool DoLayoutAdaptation(wxDialog* dialog) = 0;
 };
 
     virtual bool DoLayoutAdaptation(wxDialog* dialog) = 0;
 };
 

+
+/**
+    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;
+};