More initial reviews of d* interface headers.

[wxWidgets.git] / interface / dialog.h

diff --git a/interface/dialog.h b/interface/dialog.h
index 6c34363b9fa2697d0181df0492cf31f55af93ad6..c97cef8d8940697db8596b1c2d1b8d2675fee4f5 100644 (file)
--- a/interface/dialog.h
+++ b/interface/dialog.h
@@ -6,23 +6,88 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    Modes used for wxDialog::SetLayoutAdaptationMode().
+*/
+enum wxDialogLayoutAdaptationMode
+{
+    wxDIALOG_ADAPTATION_MODE_DEFAULT = 0,   ///< Use global adaptation enabled status.
+    wxDIALOG_ADAPTATION_MODE_ENABLED = 1,   ///< Enable this dialog overriding global status.
+    wxDIALOG_ADAPTATION_MODE_DISABLED = 2   ///< Disable this dialog overriding global status.
+};
+

 /**
     @class wxDialog
     @wxheader{dialog.h}
 
 /**
     @class wxDialog
     @wxheader{dialog.h}
 

-    A dialog box is a window with a title bar and sometimes a system menu, which
-    can be moved around the screen. It can contain controls and other windows and
-    is often used to allow the user to make some choice or to answer a question.
-
-    Dialogs can be made scrollable, automatically: please see @ref
-    overview_autoscrollingdialogs "Automatic scrolling dialogs" for further details.
+    A dialog box is a window with a title bar and sometimes a system menu,
+    which can be moved around the screen. It can contain controls and other
+    windows and is often used to allow the user to make some choice or to
+    answer a question.
+
+    Dialogs can be made scrollable, automatically, for computers with low
+    resolution screens: please see @ref overview_dialog_autoscrolling for
+    further details.
+
+    Dialogs usually contains either a single button allowing to close the
+    dialog or two buttons, one accepting the changes and the other one
+    discarding them (such button, if present, is automatically activated if the
+    user presses the "Esc" key). By default, buttons with the standard wxID_OK
+    and wxID_CANCEL identifiers behave as expected. Starting with wxWidgets 2.7
+    it is also possible to use a button with a different identifier instead,
+    see SetAffirmativeId() and SetEscapeId().
+
+    Also notice that the CreateButtonSizer() should be used to create the
+    buttons appropriate for the current platform and positioned correctly
+    (including their order which is platform-dependent).
+
+    @section dialog_modal Modal and Modeless
+
+    There are two kinds of dialog, modal and modeless. A modal dialog blocks
+    program flow and user input on other windows until it is dismissed, whereas
+    a modeless dialog behaves more like a frame in that program flow continues,
+    and input in other windows is still possible. To show a modal dialog you
+    should use the ShowModal() method while to show a dialog modelessly you
+    simply use Show(), just as with frames.
+
+    Note that the modal dialog is one of the very few examples of
+    wxWindow-derived objects which may be created on the stack and not on the
+    heap. In other words, while most windows would be created like this:
+
+    @code
+    void AskUser()
+    {
+        MyAskDialog *dlg = new MyAskDialog(...);
+        if ( dlg->ShowModal() == wxID_OK )
+            // ...
+        //else: dialog was cancelled or some another button pressed
+
+        dlg->Destroy();
+    }
+    @endcode
+
+    You can achieve the same result with dialogs by using simpler code:
+
+    @code
+    void AskUser()
+    {
+        MyAskDialog dlg(...);
+        if ( dlg.ShowModal() == wxID_OK )
+            // ...
+
+        // no need to call Destroy() here
+    }
+    @endcode
+
+    An application can define a wxCloseEvent handler for the dialog to respond
+    to system close events.

 
     @beginStyleTable
     @style{wxCAPTION}
            Puts a caption on the dialog box.
     @style{wxDEFAULT_DIALOG_STYLE}
            Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and
 
     @beginStyleTable
     @style{wxCAPTION}
            Puts a caption on the dialog box.
     @style{wxDEFAULT_DIALOG_STYLE}
            Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and

-           wxSYSTEM_MENU (the last one is not used under Unix)
+           wxSYSTEM_MENU (the last one is not used under Unix).

     @style{wxRESIZE_BORDER}
            Display a resizeable frame around the window.
     @style{wxSYSTEM_MENU}
     @style{wxRESIZE_BORDER}
            Display a resizeable frame around the window.
     @style{wxSYSTEM_MENU}


@@ -42,84 +107,89 @@
            borders unless specified in the control.
     @style{wxDIALOG_NO_PARENT}
            By default, a dialog created with a @NULL parent window will be
            borders unless specified in the control.
     @style{wxDIALOG_NO_PARENT}
            By default, a dialog created with a @NULL parent window will be

-           given the application's top level window as parent. Use this style
-           to prevent this from happening and create an orphan dialog. This is
-           not recommended for modal dialogs.
+           given the @ref wxApp::GetTopWindow() "application's top level window"
+           as parent. Use this style to prevent this from happening and create
+           an orphan dialog. This is not recommended for modal dialogs.

     @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
            window. Note that this is an extended style and must be set by
     @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
            window. Note that this is an extended style and must be set by

-           calling SetExtraStyle before Create is called (two-step
+           calling SetExtraStyle() before Create is called (two-step

            construction).
     @style{wxDIALOG_EX_METAL}
            On Mac OS X, frames with this style will be shown with a metallic
            look. This is an extra style.
     @endStyleTable
 
            construction).
     @style{wxDIALOG_EX_METAL}
            On Mac OS X, frames with this style will be shown with a metallic
            look. This is an extra style.
     @endStyleTable
 

+    Under Unix or Linux, MWM (the Motif Window Manager) or other window
+    managers recognizing the MHM hints should be running for any of these
+    styles to have an effect.
+

     @library{wxcore}
     @category{cmndlg}
 
     @library{wxcore}
     @category{cmndlg}
 

-    @see @ref overview_wxdialogoverview, wxFrame, @ref overview_validatoroverview
-    "Validator overview"
+    @see @ref overview_dialog, wxFrame, @ref overview_validator

 */
 class wxDialog : public wxTopLevelWindow
 {
 public:
 */
 class wxDialog : public wxTopLevelWindow
 {
 public:

-    //@{
+    /**
+        Default constructor.
+    */
+    wxDialog();

     /**
         Constructor.
 
         @param parent
             Can be @NULL, a frame or another dialog box.
         @param id
     /**
         Constructor.
 
         @param parent
             Can be @NULL, a frame or another dialog box.
         @param id

-            An identifier for the dialog. A value of -1 is taken to mean a default.
+            An identifier for the dialog. A value of -1 is taken to mean a
+            default.

         @param title
             The title of the dialog.
         @param pos
         @param title
             The title of the dialog.
         @param pos

-            The dialog position. The value wxDefaultPosition indicates a default position,
-        chosen by
-            either the windowing system or wxWidgets, depending on platform.
+            The dialog position. The value wxDefaultPosition indicates a
+            default position, chosen by either the windowing system or
+            wxWidgets, depending on platform.

         @param size
         @param size

-            The dialog size. The value wxDefaultSize indicates a default size, chosen by
-            either the windowing system or wxWidgets, depending on platform.
+            The dialog size. The value wxDefaultSize indicates a default size,
+            chosen by either the windowing system or wxWidgets, depending on
+            platform.

         @param style
         @param style

-            The window style. See wxDialog.
+            The window style.

         @param name
         @param name

-            Used to associate a name with the window,
-            allowing the application user to set Motif resource values for
-            individual dialog boxes.
+            Used to associate a name with the window, allowing the application
+            user to set Motif resource values for individual dialog boxes.

 
         @see Create()
     */
 
         @see Create()
     */

-    wxDialog();
-    wxDialog(wxWindow* parent, wxWindowID id,
-             const wxString& title,
+    wxDialog(wxWindow* parent, wxWindowID id, const wxString& title,

              const wxPoint& pos = wxDefaultPosition,
              const wxSize& size = wxDefaultSize,
              long style = wxDEFAULT_DIALOG_STYLE,
              const wxString& name = "dialogBox");
              const wxPoint& pos = wxDefaultPosition,
              const wxSize& size = wxDefaultSize,
              long style = wxDEFAULT_DIALOG_STYLE,
              const wxString& name = "dialogBox");

-    //@}

 
     /**
 
     /**

-        Destructor. Deletes any child windows before deleting the physical window.
+        Destructor. Deletes any child windows before deleting the physical
+        window.

     */
     ~wxDialog();
 
     /**
     */
     ~wxDialog();
 
     /**

-        Adds an identifier to be regarded as a main button for the non-scrolling area
-        of a dialog.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        Adds an identifier to be regarded as a main button for the
+        non-scrolling area of a dialog.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     void AddMainButtonId(wxWindowID id);
 
     /**
     */
     void AddMainButtonId(wxWindowID id);
 
     /**

-        Returns @true if this dialog can and should perform layout adaptation using
-        DoLayoutAdaptation(), usually if
-        the dialog is too large to fit on the display.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        Returns @true if this dialog can and should perform layout adaptation
+        using DoLayoutAdaptation(), usually if the dialog is too large to fit
+        on the display.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     bool CanDoLayoutAdapation();
 
     */
     bool CanDoLayoutAdapation();
 


@@ -132,74 +202,78 @@ public:
     void Centre(int direction = wxBOTH);
 
     /**
     void Centre(int direction = wxBOTH);
 
     /**

-        Used for two-step dialog box construction. See wxDialog()
-        for details.
+        Used for two-step dialog box construction.
+
+        @see wxDialog()

     */
     */

-    bool Create(wxWindow* parent, wxWindowID id,
-                const wxString& title,
+    bool Create(wxWindow* parent, wxWindowID id, const wxString& title,

                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxDEFAULT_DIALOG_STYLE,
                 const wxString& name = "dialogBox");
 
     /**
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxDEFAULT_DIALOG_STYLE,
                 const wxString& name = "dialogBox");
 
     /**

-        Creates a sizer with standard buttons. @a flags is a bit list
-        of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE,
-        wxHELP, wxNO_DEFAULT.
+        Creates a sizer with standard buttons. @a flags is a bit list of the
+        following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP,
+        wxNO_DEFAULT.
+

         The sizer lays out the buttons in a manner appropriate to the platform.
         The sizer lays out the buttons in a manner appropriate to the platform.

-        This function uses CreateStdDialogButtonSizer()
-        internally for most platforms but doesn't create the sizer at all for the
-        platforms with hardware buttons (such as smartphones) for which it sets up the
-        hardware buttons appropriately and returns @NULL, so don't forget to test that
-        the return value is valid before using it.
+
+        This function uses CreateStdDialogButtonSizer() internally for most
+        platforms but doesn't create the sizer at all for the platforms with
+        hardware buttons (such as smartphones) for which it sets up the
+        hardware buttons appropriately and returns @NULL, so don't forget to
+        test that the return value is valid before using it.

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

-        Creates a sizer with standard buttons using
-        CreateButtonSizer() separated from the rest
-        of the dialog contents by a horizontal wxStaticLine.
-        Please notice that just like CreateButtonSizer() this function may return @c
-        @NULL
-        if no buttons were created.
+        Creates a sizer with standard buttons using CreateButtonSizer()
+        separated from the rest of the dialog contents by a horizontal
+        wxStaticLine.
+
+        @note Just like CreateButtonSizer(), this function may return @NULL if
+              no buttons were created.

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

-        Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a bit list
-        of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE,
-        wxHELP, wxNO_DEFAULT.
+        Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a
+        bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY,
+        wxCLOSE, wxHELP, wxNO_DEFAULT.
+

         The sizer lays out the buttons in a manner appropriate to the platform.
     */
     wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags);
 
     /**
         The sizer lays out the buttons in a manner appropriate to the platform.
     */
     wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags);
 
     /**

-        Performs layout adaptation, usually if the dialog is too large to fit on the
-        display.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        Performs layout adaptation, usually if the dialog is too large to fit
+        on the display.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     bool DoLayoutAdapation();
 
     /**
     */
     bool DoLayoutAdapation();
 
     /**

-        This function is called when the titlebar OK button is pressed (PocketPC only).
-        A command event for the identifier returned by GetAffirmativeId is sent by
-        default. You can override this function. If the function returns @false,
-        wxWidgets
-        will call Close() for the dialog.
+        This function is called when the titlebar OK button is pressed
+        (PocketPC only). A command event for the identifier returned by
+        GetAffirmativeId() is sent by default. You can override this function.
+        If the function returns @false, wxWidgets will call Close() for the
+        dialog.

     */
     virtual bool DoOK();
 
     /**
     */
     virtual bool DoOK();
 
     /**

-        A static function enabling or disabling layout adaptation for all dialogs.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        A static function enabling or disabling layout adaptation for all
+        dialogs.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     static void EnableLayoutAdaptation(bool enable);
 
     /**
     */
     static void EnableLayoutAdaptation(bool enable);
 
     /**

-        Ends a modal dialog, passing a value to be returned from the ShowModal()
-        invocation.
+        Ends a modal dialog, passing a value to be returned from the
+        ShowModal() invocation.

 
         @param retCode
             The value that should be returned by ShowModal.
 
         @param retCode
             The value that should be returned by ShowModal.


@@ -209,76 +283,74 @@ public:
     void EndModal(int retCode);
 
     /**
     void EndModal(int retCode);
 
     /**

-        Gets the identifier of the button which works like standard OK button in this
-        dialog.
+        Gets the identifier of the button which works like standard OK button
+        in this dialog.

 
         @see SetAffirmativeId()
     */
     int GetAffirmativeId() const;
 
     /**
 
         @see SetAffirmativeId()
     */
     int GetAffirmativeId() const;
 
     /**

-        Override this to return a window containing the main content of the dialog.
-        This is
-        particularly useful when the dialog implements pages, such as
-        wxPropertySheetDialog,
-        and allows the @ref overview_wxdialogoverview "layout adaptation code" to know
-        that only the pages need to be made scrollable.
+        Override this to return a window containing the main content of the
+        dialog. This is particularly useful when the dialog implements pages,
+        such as wxPropertySheetDialog, and allows the
+        @ref overview_dialog "layout adaptation code" to know that only the
+        pages need to be made scrollable.

     */
     wxWindow* GetContentWindow() const;
 
     /**
     */
     wxWindow* GetContentWindow() const;
 
     /**

-        Gets the identifier of the button to map presses of @c ESC
-        button to.
+        Gets the identifier of the button to map presses of @c ESC button to.

 
         @see SetEscapeId()
     */
     int GetEscapeId() const;
 
     /**
 
         @see SetEscapeId()
     */
     int GetEscapeId() const;
 
     /**

-        Returns @true if the dialog has been adapted, usually by making it scrollable
-        to work with a small display.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        Returns @true if the dialog has been adapted, usually by making it
+        scrollable to work with a small display.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     bool GetLayoutAdaptationDone() const;
 
     /**
     */
     bool GetLayoutAdaptationDone() const;
 
     /**

-        Gets a value representing the aggressiveness of search for buttons and sizers
-        to be in the non-scrolling part of a layout-adapted dialog.
-        Zero switches off adaptation, and 3 allows search for standard buttons anywhere
-        in the dialog.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        Gets a value representing the aggressiveness of search for buttons and
+        sizers to be in the non-scrolling part of a layout-adapted dialog. Zero
+        switches off adaptation, and 3 allows search for standard buttons
+        anywhere in the dialog.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     int GetLayoutAdaptationLevel();
 
     /**
         Gets the adaptation mode, overriding the global adaptation flag.
     */
     int GetLayoutAdaptationLevel();
 
     /**
         Gets the adaptation mode, overriding the global adaptation flag.

-        See also SetLayoutAdaptationMode() and @ref overview_autoscrollingdialogs
-        "Automatic scrolling dialogs".
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     wxDialogLayoutAdaptationMode GetLayoutAdaptationMode() const;
 
     /**
         A static function getting the current layout adapter object.
     */
     wxDialogLayoutAdaptationMode GetLayoutAdaptationMode() const;
 
     /**
         A static function getting the current layout adapter object.

-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     static wxDialogLayoutAdapter* GetLayoutAdapter();
 
     /**
     */
     static wxDialogLayoutAdapter* GetLayoutAdapter();
 
     /**

-        Returns an array of identifiers to be regarded as the main buttons for the
-        non-scrolling area of a dialog.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        Returns an array of identifiers to be regarded as the main buttons for
+        the non-scrolling area of a dialog.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     wxArrayInt GetMainButtonIds();
 
     /**
         Gets the return code for this window.
 
     */
     wxArrayInt GetMainButtonIds();
 
     /**
         Gets the return code for this window.
 

-        @remarks A return code is normally associated with a modal dialog, where
-                 ShowModal() returns a code to the application.
+        @remarks A return code is normally associated with a modal dialog,
+                 where ShowModal() returns a code to the application.

 
         @see SetReturnCode(), ShowModal(), EndModal()
     */
 
         @see SetReturnCode(), ShowModal(), EndModal()
     */


@@ -286,9 +358,10 @@ public:
 
     /**
         On PocketPC, a dialog is automatically provided with an empty toolbar.
 
     /**
         On PocketPC, a dialog is automatically provided with an empty toolbar.

-        GetToolBar
-        allows you to access the toolbar and add tools to it. Removing tools and adding
-        arbitrary controls are not currently supported.
+        This function allows you to access the toolbar and add tools to it.
+        Removing tools and adding arbitrary controls are not currently
+        supported.
+

         This function is not available on any other platform.
     */
     wxToolBar* GetToolBar() const;
         This function is not available on any other platform.
     */
     wxToolBar* GetToolBar() const;


@@ -300,11 +373,11 @@ public:
             If @true, iconizes the dialog box; if @false, shows and restores it.
 
         @remarks Note that in Windows, iconization has no effect since dialog
             If @true, iconizes the dialog box; if @false, shows and restores it.
 
         @remarks Note that in Windows, iconization has no effect since dialog

-                 boxes cannot be iconized. However, applications may
-                 need to explicitly restore dialog boxes under Motif
-                 which have user-iconizable frames, and under Windows
-                 calling Iconize(@false) will bring the window to the
-                 front, as does Show(@true).
+                 boxes cannot be iconized. However, applications may need to
+                 explicitly restore dialog boxes under Motif which have
+                 user-iconizable frames, and under Windows calling
+                 Iconize(@false) will bring the window to the front, as does
+                 Show(@true).

     */
     void Iconize(bool iconize);
 
     */
     void Iconize(bool iconize);
 


@@ -317,18 +390,18 @@ public:
     bool IsIconized() const;
 
     /**
     bool IsIconized() const;
 
     /**

-        A static function returning @true if layout adaptation is enabled for all
-        dialogs.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        A static function returning @true if layout adaptation is enabled for
+        all dialogs.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     static bool IsLayoutAdaptationEnabled();
 
     /**
     */
     static bool IsLayoutAdaptationEnabled();
 
     /**

-        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.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        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.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     bool IsMainButton(wxWindowID& id) const;
 
     */
     bool IsMainButton(wxWindowID& id) const;
 


@@ -344,12 +417,11 @@ public:
             The colour change event.
 
         @remarks Changes the dialog's colour to conform to the current settings
             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.
+                 (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
     */
 
         @see wxSysColourChangedEvent
     */


@@ -357,13 +429,14 @@ public:
 
     /**
         Sets the identifier to be used as OK button. When the button with this
 
     /**
         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 @c wxID_OK 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 this id is
-        generated.
+        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.
+
+        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
+        this id is generated.
+

         By default, the affirmative id is wxID_OK.
 
         @see GetAffirmativeId(), SetEscapeId()
         By default, the affirmative id is wxID_OK.
 
         @see GetAffirmativeId(), SetEscapeId()


@@ -372,16 +445,17 @@ public:
 
     /**
         Sets the identifier of the button which should work like the standard
 
     /**
         Sets the identifier of the button which should work like the standard

-        @c CANCEL button in this dialog. When the button with this id is
-        clicked, the dialog is closed. Also, when the user presses @c ESC
-        key in the dialog or closes the dialog using the close button in the title bar,
-        this is mapped to the click of the button with the specified id.
-        By default, the escape id is the special value @c wxID_ANY meaning that
-        @c wxID_CANCEL button is used if it's present in the dialog and
-        otherwise the button with GetAffirmativeId()
-        is used. Another special value for @a id is @c wxID_NONE meaning that
-        @c ESC presses should be ignored. If any other value is given, it
-        is interpreted as the id of the button to map the escape key to.
+        "Cancel" button in this dialog. When the button with this id is
+        clicked, the dialog is closed. Also, when the user presses @c ESC key
+        in the dialog or closes the dialog using the close button in the title
+        bar, this is mapped to the click of the button with the specified id.
+
+        By default, the escape id is the special value wxID_ANY meaning that
+        wxID_CANCEL button is used if it's present in the dialog and otherwise
+        the button with GetAffirmativeId() is used. Another special value for
+        @a id is wxID_NONE meaning that @c ESC presses should be ignored. If
+        any other value is given, it is interpreted as the id of the button to
+        map the escape key to.

     */
     void SetEscapeId(int id);
 
     */
     void SetEscapeId(int id);
 


@@ -390,6 +464,8 @@ public:
 
         @param icon
             The icon to associate with this dialog.
 
         @param icon
             The icon to associate with this dialog.

+
+        @see wxIcon

     */
     void SetIcon(const wxIcon& icon);
 
     */
     void SetIcon(const wxIcon& icon);
 


@@ -398,51 +474,53 @@ public:
 
         @param icons
             The icons to associate with this dialog.
 
         @param icons
             The icons to associate with this dialog.

+
+        @see wxIconBundle

     */
     void SetIcons(const wxIconBundle& icons);
 
     /**
     */
     void SetIcons(const wxIconBundle& icons);
 
     /**

-        Marks the dialog as having been adapted, usually by making it scrollable to
-        work with a small display.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        Marks the dialog as having been adapted, usually by making it
+        scrollable to work with a small display.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     void SetLayoutAdaptationDone(bool done);
 
     /**
         Sets the aggressiveness of search for buttons and sizers to be in the
     */
     void SetLayoutAdaptationDone(bool done);
 
     /**
         Sets the aggressiveness of search for buttons and sizers to be in the

-        non-scrolling part of a layout-adapted dialog.
-        Zero switches off adaptation, and 3 allows search for standard buttons anywhere
-        in the dialog.
-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        non-scrolling part of a layout-adapted dialog. Zero switches off
+        adaptation, and 3 allows search for standard buttons anywhere in the
+        dialog.
+
+        @see @ref overview_dialog_autoscrolling (for more on layout adaptation)

     */
     void SetLayoutAdaptationLevel(int level);
 
     /**
     */
     void SetLayoutAdaptationLevel(int level);
 
     /**

-        Sets the adaptation mode, overriding the global adaptation flag. @a mode may be
-        one of the following values:
+        Sets the adaptation mode, overriding the global adaptation flag.

 
 

-        See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
-        more on layout adaptation.
+        @see wxDialogLayoutAdaptationMode, @ref overview_dialog_autoscrolling
+             (for more on layout adaptation)

     */
     void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode);
 
     /**
     */
     void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode);
 
     /**

-        A static function for setting the current layout adapter object, returning the
-        old adapter. If you call this, you should
-        delete the old adapter object.
-        See also wxDialogLayoutAdapter and @ref overview_autoscrollingdialogs
-        "Automatic scrolling dialogs".
+        A static function for setting the current layout adapter object,
+        returning the old adapter. If you call this, you should delete the old
+        adapter object.
+
+        @see wxDialogLayoutAdapter, @ref overview_dialog_autoscrolling

     */
     static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter);
 
     /**
     */
     static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter);
 
     /**

-        @note This function is deprecated and 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).
+        @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.
 
         @param flag
             If @true, the dialog will be modal, otherwise it will be modeless.


@@ -452,36 +530,35 @@ public:
     /**
         Sets the return code for this window.
 
     /**
         Sets the return code for this window.
 

+        A return code is normally associated with a modal dialog, where
+        ShowModal() returns a code to the application. The function EndModal()
+        calls SetReturnCode().
+

         @param retCode
             The integer return code, usually a control identifier.
 
         @param retCode
             The integer return code, usually a control identifier.
 

-        @remarks A return code is normally associated with a modal dialog, where
-                 ShowModal() returns a code to the application.
-                 The function EndModal() calls SetReturnCode.
-

         @see GetReturnCode(), ShowModal(), EndModal()
     */
     void SetReturnCode(int retCode);
 
     /**
         @see GetReturnCode(), ShowModal(), EndModal()
     */
     void SetReturnCode(int retCode);
 
     /**

-        Hides or shows the dialog.
+        Hides or shows the dialog. The preferred way of dismissing a modal
+        dialog is to use EndModal().

 
         @param show
 
         @param show

-            If @true, the dialog box is shown and brought to the front;
-            otherwise the box is hidden. If @false and the dialog is
-            modal, control is returned to the calling program.
-
-        @remarks The preferred way of dismissing a modal dialog is to use
-                 EndModal().
+            If @true, the dialog box is shown and brought to the front,
+            otherwise the box is hidden. If @false and the dialog is modal,
+            control is returned to the calling program.

     */
     bool Show(bool show);
 
     /**
     */
     bool Show(bool show);
 
     /**

-        Shows a modal dialog. Program flow does not return until the dialog has been
-        dismissed with
-        EndModal().
+        Shows a modal dialog. Program flow does not return until the dialog has
+        been dismissed with EndModal().
+
+        @returns The value set with SetReturnCode().

 
 

-        @returns The return value is the value set with SetReturnCode().
+        @see EndModal(), GetReturnCode(), SetReturnCode()

     */
     int ShowModal();
 };
     */
     int ShowModal();
 };


@@ -492,21 +569,19 @@ public:
     @class wxDialogLayoutAdapter
     @wxheader{dialog.h}
 
     @class wxDialogLayoutAdapter
     @wxheader{dialog.h}
 

-    This abstract class is the base for classes that help wxWidgets peform 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.
+    This abstract class is the base for classes that help wxWidgets peform
+    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.

 
 

-    By default, there is one instance of wxStandardDialogLayoutAdapter
-    which can perform adaptation for most custom dialogs and dialogs with book
-    controls
-    such as wxPropertySheetDialog.
+    By default, there is one instance of wxStandardDialogLayoutAdapter which
+    can perform adaptation for most custom dialogs and dialogs with book
+    controls such as wxPropertySheetDialog.

 
     @library{wxcore}
 
     @library{wxcore}

-    @category{FIXME}
+    @category{winlayout}

 
 

-    @see @ref overview_autoscrollingdialogs "Automatic scrolling dialogs"
+    @see @ref overview_dialog_autoscrolling

 */
 class wxDialogLayoutAdapter
 {
 */
 class wxDialogLayoutAdapter
 {


@@ -522,9 +597,9 @@ public:
     bool CanDoLayoutAdaptation(wxDialog* dialog);
 
     /**
     bool CanDoLayoutAdaptation(wxDialog* dialog);
 
     /**

-        Override this to perform layout adaptation, such as making parts of the dialog
-        scroll and resizing the dialog to fit the display.
-        Normally this function will be called just before the dialog is shown.
+        Override this to perform layout adaptation, such as making parts of the
+        dialog scroll and resizing the dialog to fit the display. Normally this
+        function will be called just before the dialog is shown.

     */
     bool DoLayoutAdaptation(wxDialog* dialog);
 };
     */
     bool DoLayoutAdaptation(wxDialog* dialog);
 };