Fixed typo in wxFileName::GetHumanReadableSize docs.

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

diff --git a/interface/wx/dialog.h b/interface/wx/dialog.h
index 702595a34c20a131842e722118664013e052a17f..093d0c42ec6382eae89ef13dfd4e27b61570ff0d 100644 (file)
--- a/interface/wx/dialog.h
+++ b/interface/wx/dialog.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxDialog
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -112,7 +112,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
-           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).
@@ -125,6 +125,18 @@ enum wxDialogLayoutAdaptationMode
     managers recognizing the MHM hints should be running for any of these
     styles to have an effect.
 
+
+    @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_INIT_DIALOG(func)}
+        Process a @c wxEVT_INIT_DIALOG event. See wxInitDialogEvent.
+    @endEventTable
+
     @library{wxcore}
     @category{cmndlg}
 
@@ -170,8 +182,11 @@ public:
              const wxString& name = wxDialogNameStr);
 
     /**
-        Destructor. Deletes any child windows before deleting the physical
-        window.
+        Destructor.
+
+        Deletes any child windows before deleting the physical window.
+
+        See @ref overview_windowdeletion for more info.
     */
     virtual ~wxDialog();
 
@@ -233,9 +248,30 @@ public:
 
         @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);
 
+    /**
+        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,
@@ -416,7 +452,7 @@ public:
     virtual bool IsModal() const;
 
     /**
-        The default handler for wxEVT_SYS_COLOUR_CHANGED.
+        The default handler for @c wxEVT_SYS_COLOUR_CHANGED.
 
         @param event
             The colour change event.
@@ -436,7 +472,7 @@ public:
         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
@@ -558,7 +594,7 @@ public:
     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().
@@ -568,11 +604,33 @@ public:
         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().
 
-        @see EndModal(), GetReturnCode(), SetReturnCode()
+        @see ShowWindowModal(), EndModal(), GetReturnCode(), SetReturnCode()
     */
     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 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).
+
+        @since 2.9.0
+     */
+    void ShowWindowModal();
 };