Fix typo in wxStandardPathsBase::ResourceCat description and document it.

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

diff --git a/interface/wx/dialog.h b/interface/wx/dialog.h
index 0ffb51d8836d23aefe7d6b74a79573bca2659ee2..69a58d43a8a4193e2b0f925c6cbf885942886ab7 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
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -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();
 
@@ -190,7 +205,7 @@ public:
 
         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
     */
-    bool CanDoLayoutAdapation();
+    virtual bool CanDoLayoutAdaptation();
 
     /**
         Centres the dialog box on the display.
@@ -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,
@@ -251,7 +287,7 @@ public:
 
         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
     */
-    bool DoLayoutAdapation();
+    virtual bool DoLayoutAdaptation();
 
     /**
         This function is called when the titlebar OK button is pressed
@@ -259,6 +295,8 @@ public:
         GetAffirmativeId() is sent by default. You can override this function.
         If the function returns @false, wxWidgets will call Close() for the
         dialog.
+
+        @onlyfor{wxmsw}
     */
     virtual bool DoOK();
 
@@ -362,6 +400,8 @@ public:
         supported.
 
         This function is not available on any other platform.
+
+        @onlyfor{wxmsw}
     */
     wxToolBar* GetToolBar() const;
 
@@ -400,9 +440,11 @@ public:
         Returns @true if @a id is in the array of identifiers to be regarded as
         the main buttons for the non-scrolling area of a dialog.
 
+        @onlyfor{wxmsw}
+
         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
     */
-    bool IsMainButton(wxWindowID& id) const;
+    bool IsMainButtonId(wxWindowID id) const;
 
     /**
         Returns @true if the dialog box is modal, @false otherwise.
@@ -562,6 +604,11 @@ 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()