mac paths updated

[wxWidgets.git] / interface / dialog.h

diff --git a/interface/dialog.h b/interface/dialog.h
index 73543c1f58c3d3761a8f1cb479d7b706c6c0f2bb..431edf62b757e073c484dded912bafd7ab1d3744 100644 (file)
--- a/interface/dialog.h
+++ b/interface/dialog.h
@@ -6,120 +6,190 @@
 // 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
 
     @beginStyleTable

-    @style{wxCAPTION}:
+    @style{wxCAPTION}

            Puts a caption on the dialog box.
            Puts a caption on the dialog box.

-    @style{wxDEFAULT_DIALOG_STYLE}:
+    @style{wxDEFAULT_DIALOG_STYLE}

            Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and
            Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and

-           wxSYSTEM_MENU (the last one is not used under Unix)
-    @style{wxRESIZE_BORDER}:
+           wxSYSTEM_MENU (the last one is not used under Unix).
+    @style{wxRESIZE_BORDER}

            Display a resizeable frame around the window.
            Display a resizeable frame around the window.

-    @style{wxSYSTEM_MENU}:
+    @style{wxSYSTEM_MENU}

            Display a system menu.
            Display a system menu.

-    @style{wxCLOSE_BOX}:
+    @style{wxCLOSE_BOX}

            Displays a close box on the frame.
            Displays a close box on the frame.

-    @style{wxMAXIMIZE_BOX}:
+    @style{wxMAXIMIZE_BOX}

            Displays a maximize box on the dialog.
            Displays a maximize box on the dialog.

-    @style{wxMINIMIZE_BOX}:
+    @style{wxMINIMIZE_BOX}

            Displays a minimize box on the dialog.
            Displays a minimize box on the dialog.

-    @style{wxTHICK_FRAME}:
+    @style{wxTHICK_FRAME}

            Display a thick frame around the window.
            Display a thick frame around the window.

-    @style{wxSTAY_ON_TOP}:
+    @style{wxSTAY_ON_TOP}

            The dialog stays on top of all other windows.
            The dialog stays on top of all other windows.

-    @style{wxNO_3D}:
+    @style{wxNO_3D}

            Under Windows, specifies that the child controls should not have 3D
            borders unless specified in the control.
            Under Windows, specifies that the child controls should not have 3D
            borders unless specified in the control.

-    @style{wxDIALOG_NO_PARENT}:
+    @style{wxDIALOG_NO_PARENT}

            By default, a dialog created with a @NULL parent window will be
            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.
-    @style{wxDIALOG_EX_CONTEXTHELP}:
+           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
            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).
            construction).

-    @style{wxDIALOG_EX_METAL}:
+    @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
 
            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().
+
+        @return 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);
 };