documentation for window ids allocation and wxIdManager (patch 1870570)

[wxWidgets.git] / docs / latex / wx / dialog.tex

diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex
index cca1f238b8e5b342ddf31046e038645584592ee7..f6fa0d826100714ba1b8f62d064879a255c22a60 100644 (file)
--- a/docs/latex/wx/dialog.tex
+++ b/docs/latex/wx/dialog.tex
@@ -1,8 +1,36 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        dialog.tex
+%% Purpose:     wxDialog documentation
+%% Author:      wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID:      $Id$
+%% Copyright:   (c) wxWidgets Team
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+

 \section{\class{wxDialog}}\label{wxdialog}
 
 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
 \section{\class{wxDialog}}\label{wxdialog}
 
 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 usually used to allow the user to make some choice or to answer a question.
+is often used to allow the user to make some choice or to answer a question.
+
+Dialogs can be made scrollable, automatically: please see \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for further details.
+
+\wxheading{Dialog Buttons}
+
+The dialog 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 \texttt{"Esc"} key). By default, buttons with the standard \texttt{wxID\_OK} 
+and \texttt{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 \helpref{SetAffirmativeId}{wxdialogsetaffirmativeid} and 
+\helpref{SetEscapeId}{wxdialogsetescapeid}.
+
+Also notice that the \helpref{CreateButtonSizer()}{wxdialogcreatebuttonsizer} 
+should be used to create the buttons appropriate for the current platform and
+positioned correctly (including their order which is platform-dependent).

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 


@@ -15,7 +43,11 @@ is usually used to allow the user to make some choice or to answer a question.
 
 <wx/dialog.h>
 
 
 <wx/dialog.h>
 

-\wxheading{Remarks}
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
+\wxheading{Modal and modeless dialogs}

 
 There are two kinds of dialog -- {\it modal}\ and {\it modeless}. A modal dialog
 blocks program flow and user input on other windows until it is dismissed,
 
 There are two kinds of dialog -- {\it modal}\ and {\it modeless}. A modal dialog
 blocks program flow and user input on other windows until it is dismissed,


@@ -55,7 +87,7 @@ below:
     }
 \end{verbatim}
 
     }
 \end{verbatim}
 

-An application can define an \helpref{wxCloseEvent}{wxcloseevent} handler for
+An application can define a \helpref{wxCloseEvent}{wxcloseevent} handler for

 the dialog to respond to system close events.
 
 \wxheading{Window styles}
 the dialog to respond to system close events.
 
 \wxheading{Window styles}


@@ -70,17 +102,18 @@ the dialog to respond to system close events.
 \twocolitem{\windowstyle{wxMAXIMIZE\_BOX}}{Displays a maximize box on the dialog.}
 \twocolitem{\windowstyle{wxMINIMIZE\_BOX}}{Displays a minimize box on the dialog.}
 \twocolitem{\windowstyle{wxTHICK\_FRAME}}{Display a thick frame around the window.}
 \twocolitem{\windowstyle{wxMAXIMIZE\_BOX}}{Displays a maximize box on the dialog.}
 \twocolitem{\windowstyle{wxMINIMIZE\_BOX}}{Displays a minimize box on the dialog.}
 \twocolitem{\windowstyle{wxTHICK\_FRAME}}{Display a thick frame around the window.}

-\twocolitem{\windowstyle{wxSTAY\_ON\_TOP}}{The dialog stays on top of all other windows (Windows only).}
+\twocolitem{\windowstyle{wxSTAY\_ON\_TOP}}{The dialog stays on top of all other windows.}

 \twocolitem{\windowstyle{wxNO\_3D}}{Under Windows, specifies that the child controls
 should not have 3D borders unless specified in the control.}
 \twocolitem{\windowstyle{wxDIALOG\_NO\_PARENT}}{By default, a dialog created
 \twocolitem{\windowstyle{wxNO\_3D}}{Under Windows, specifies that the child controls
 should not have 3D borders unless specified in the control.}
 \twocolitem{\windowstyle{wxDIALOG\_NO\_PARENT}}{By default, a dialog created

-with a {\tt NULL} parent window will be given the 
+with a {\tt NULL} parent window will be given the

 \helpref{application's top level window}{wxappgettopwindow} as parent. Use this
 style to prevent this from happening and create an orphan dialog. This is not recommended for modal dialogs.}
 \twocolitem{\windowstyle{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. {\it Note}\ that this is an extended
 style and must be set by calling \helpref{SetExtraStyle}{wxwindowsetextrastyle} before Create is called (two-step construction).}
 \helpref{application's top level window}{wxappgettopwindow} as parent. Use this
 style to prevent this from happening and create an orphan dialog. This is not recommended for modal dialogs.}
 \twocolitem{\windowstyle{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. {\it Note}\ that this is an extended
 style and must be set by calling \helpref{SetExtraStyle}{wxwindowsetextrastyle} before Create is called (two-step construction).}

+\twocolitem{\windowstyle{wxDIALOG\_EX\_METAL}}{On Mac OS X, frames with this style will be shown with a metallic look. This is an {\it extra} style.}

 \end{twocollist}
 
 Under Unix or Linux, MWM (the Motif Window Manager) or other window managers
 \end{twocollist}
 
 Under Unix or Linux, MWM (the Motif Window Manager) or other window managers


@@ -96,6 +129,7 @@ See also \helpref{Generic window styles}{windowstyles}.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

+

 \membersection{wxDialog::wxDialog}\label{wxdialogctor}
 
 \func{}{wxDialog}{\void}
 \membersection{wxDialog::wxDialog}\label{wxdialogctor}
 
 \func{}{wxDialog}{\void}


@@ -135,12 +169,30 @@ individual dialog boxes.}
 
 \helpref{wxDialog::Create}{wxdialogcreate}
 
 
 \helpref{wxDialog::Create}{wxdialogcreate}
 

+

 \membersection{wxDialog::\destruct{wxDialog}}\label{wxdialogdtor}
 
 \func{}{\destruct{wxDialog}}{\void}
 
 Destructor. Deletes any child windows before deleting the physical window.
 
 \membersection{wxDialog::\destruct{wxDialog}}\label{wxdialogdtor}
 
 \func{}{\destruct{wxDialog}}{\void}
 
 Destructor. Deletes any child windows before deleting the physical window.
 

+\membersection{wxDialog::AddMainButtonId}\label{wxdialogaddmainbuttonid}
+
+\func{void}{AddMainButtonId}{\param{wxWindowID}{ id}}
+
+Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog.
+
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+
+\membersection{wxDialog::CanDoLayoutAdaptation}\label{wxdialogcandolayoutadaptation}
+
+\func{bool}{CanDoLayoutAdapation}{\void}
+
+Returns \true if this dialog can and should perform layout adaptation using \helpref{DoLayoutAdaptation}{wxdialogdolayoutadaptation}, usually if
+the dialog is too large to fit on the display.
+
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+

 \membersection{wxDialog::Centre}\label{wxdialogcentre}
 
 \func{void}{Centre}{\param{int}{ direction = wxBOTH}}
 \membersection{wxDialog::Centre}\label{wxdialogcentre}
 
 \func{void}{Centre}{\param{int}{ direction = wxBOTH}}


@@ -151,6 +203,7 @@ Centres the dialog box on the display.
 
 \docparam{direction}{May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL} or {\tt wxBOTH}.}
 
 
 \docparam{direction}{May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL} or {\tt wxBOTH}.}
 

+

 \membersection{wxDialog::Create}\label{wxdialogcreate}
 
 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
 \membersection{wxDialog::Create}\label{wxdialogcreate}
 
 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp


@@ -163,6 +216,72 @@ Centres the dialog box on the display.
 Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogctor}\rtfsp
 for details.
 
 Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogctor}\rtfsp
 for details.
 

+
+\membersection{wxDialog::CreateButtonSizer}\label{wxdialogcreatebuttonsizer}
+
+\func{wxSizer*}{CreateButtonSizer}{\param{long}{ flags}}
+
+Creates a sizer with standard buttons. {\it 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.
+
+This function uses \helpref{CreateStdDialogButtonSizer}{wxdialogcreatestddialogbuttonsizer} 
+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.
+
+
+\membersection{wxDialog::CreateSeparatedButtonSizer}\label{wxdialogcreateseparatedbuttonsizer}
+
+\func{wxSizer*}{CreateSeparatedButtonSizer}{\param{long}{ flags}}
+
+Creates a sizer with standard buttons using 
+\helpref{CreateButtonSizer}{wxdialogcreatebuttonsizer} separated from the rest
+of the dialog contents by a horizontal \helpref{wxStaticLine}{wxstaticline}.
+
+Please notice that just like CreateButtonSizer() this function may return \NULL 
+if no buttons were created.
+
+
+\membersection{wxDialog::CreateStdDialogButtonSizer}\label{wxdialogcreatestddialogbuttonsizer}
+
+\func{wxStdDialogButtonSizer*}{CreateStdDialogButtonSizer}{\param{long}{ flags}}
+
+Creates a \helpref{wxStdDialogButtonSizer}{wxstddialogbuttonsizer} with standard buttons. {\it 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.
+
+\membersection{wxDialog::DoLayoutAdaptation}\label{wxdialogdolayoutadaptation}
+
+\func{bool}{DoLayoutAdapation}{\void}
+
+Performs layout adaptation, usually if the dialog is too large to fit on the display.
+
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+
+\membersection{wxDialog::DoOK}\label{wxdialogdook}
+
+\func{virtual bool}{DoOK}{\void}
+
+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.
+
+\membersection{wxDialog::EnableLayoutAdaptation}\label{wxdialogenablelayoutadaptation}
+
+\func{static void}{EnableLayoutAdaptation}{\param{bool}{ enable}}
+
+A static function enabling or disabling layout adaptation for all dialogs.
+
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+
+

 \membersection{wxDialog::EndModal}\label{wxdialogendmodal}
 
 \func{void}{EndModal}{\param{int }{retCode}}
 \membersection{wxDialog::EndModal}\label{wxdialogendmodal}
 
 \func{void}{EndModal}{\param{int }{retCode}}


@@ -180,6 +299,82 @@ invocation.
 \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp
 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
 
 \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp
 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
 

+
+\membersection{wxDialog::GetAffirmativeId}\label{wxdialoggetaffirmativeid}
+
+\constfunc{int}{GetAffirmativeId}{\void}
+
+Gets the identifier of the button which works like standard OK button in this
+dialog.
+
+\wxheading{See also}
+
+\helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid}
+
+\membersection{wxDialog::GetContentWindow}\label{wxdialoggetcontentwindow}
+
+\constfunc{wxWindow*}{GetContentWindow}{\void}
+
+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 \helpref{layout adaptation code}{wxdialogoverview} to know that only the pages need to be made scrollable.
+
+\membersection{wxDialog::GetEscapeId}\label{wxdialoggetescapeid}
+
+\constfunc{int}{GetEscapeId}{\void}
+
+Gets the identifier of the button to map presses of \texttt{\textsc{ESC}}
+button to.
+
+\wxheading{See also}
+
+\helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid}
+
+
+\membersection{wxDialog::GetLayoutAdaptationDone}\label{wxdialoggetlayoutadaptationdone}
+
+\constfunc{bool}{GetLayoutAdaptationDone}{\void}
+
+Returns \true if the dialog has been adapted, usually by making it scrollable to work with a small display.
+
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+
+
+\membersection{wxDialog::GetLayoutAdaptationLevel}\label{wxdialoggetlayoutadaptationlevel}
+
+\func{int}{GetLayoutAdaptationLevel}{\void}
+
+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 \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+
+
+\membersection{wxDialog::GetLayoutAdaptationMode}\label{wxdialoggetlayoutadaptationmode}
+
+\constfunc{wxDialogLayoutAdaptationMode}{GetLayoutAdaptationMode}{\void}
+
+Gets the adaptation mode, overriding the global adaptation flag.
+
+See also \helpref{SetLayoutAdaptationMode}{wxdialogsetlayoutadaptationmode} and \helpref{Automatic scrolling dialogs}{autoscrollingdialogs}.
+
+\membersection{wxDialog::GetLayoutAdapter}\label{wxdialoggetlayoutadapter}
+
+\func{static wxDialogLayoutAdapter*}{GetLayoutAdapter}{\void}
+
+A static function getting the current layout adapter object.
+
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+
+
+\membersection{wxDialog::GetMainButtonIds}\label{wxdialoggetmainbuttonids}
+
+\func{wxArrayInt\&}{GetMainButtonIds}{\void}
+
+Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.
+
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+

 \membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode}
 
 \func{int}{GetReturnCode}{\void}
 \membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode}
 
 \func{int}{GetReturnCode}{\void}


@@ -196,15 +391,21 @@ a code to the application.
 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 
 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 

-\membersection{wxDialog::GetTitle}\label{wxdialoggettitle}

 
 

-\constfunc{wxString}{GetTitle}{\void}
+\membersection{wxDialog::GetToolBar}\label{wxdialoggettoolbar}
+
+\constfunc{wxToolBar*}{GetToolBar}{\void}
+
+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 is not available on any other platform.

 
 

-Returns the title of the dialog box.

 
 \membersection{wxDialog::Iconize}\label{wxdialogiconized}
 
 
 \membersection{wxDialog::Iconize}\label{wxdialogiconized}
 

-\func{void}{Iconize}{\param{const bool}{ iconize}}
+\func{void}{Iconize}{\param{bool}{ iconize}}

 
 Iconizes or restores the dialog. Windows only.
 
 
 Iconizes or restores the dialog. Windows only.
 


@@ -220,6 +421,7 @@ boxes under Motif which have user-iconizable frames, and under Windows
 calling {\tt Iconize(false)} will bring the window to the front, as does
 \rtfsp{\tt Show(true)}.
 
 calling {\tt Iconize(false)} will bring the window to the front, as does
 \rtfsp{\tt Show(true)}.
 

+

 \membersection{wxDialog::IsIconized}\label{wxdialogisiconized}
 
 \constfunc{bool}{IsIconized}{\void}
 \membersection{wxDialog::IsIconized}\label{wxdialogisiconized}
 
 \constfunc{bool}{IsIconized}{\void}


@@ -230,93 +432,94 @@ Returns true if the dialog box is iconized. Windows only.
 
 Always returns false under Windows since dialogs cannot be iconized.
 
 
 Always returns false under Windows since dialogs cannot be iconized.
 

-\membersection{wxDialog::IsModal}\label{wxdialogismodal}

 
 

-\constfunc{bool}{IsModal}{\void}
+\membersection{wxDialog::IsLayoutAdaptationEnabled}\label{wxdialogislayoutadaptationenabled}

 
 

-Returns true if the dialog box is modal, false otherwise.
+\func{static bool}{IsLayoutAdaptationEnabled}{\void}

 
 

-\membersection{wxDialog::OnCharHook}\label{wxdialogoncharhook}
+A static function returning \true if layout adaptation is enabled for all dialogs.

 
 

-\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.

 
 

-This member is called to allow the window to intercept keyboard events
-before they are processed by child windows.

 
 

-%For more information, see \helpref{wxWindow::OnCharHook}{wxwindowoncharhook}
+\membersection{wxDialog::IsMainButton}\label{wxdialogismainbutton}

 
 

-\wxheading{Remarks}
+\constfunc{bool}{IsMainButton}{\param{wxWindowID\& }{id}}

 
 

-wxDialog implements this handler to fake a cancel command if the escape key has been
-pressed. This will dismiss the dialog.
+Returns \true if {\it id} is in the array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.

 
 

-\membersection{wxDialog::OnApply}\label{wxdialogonapply}
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.

 
 

-\func{void}{OnApply}{\param{wxCommandEvent\& }{event}}

 
 

-The default handler for the wxID\_APPLY identifier.
+\membersection{wxDialog::IsModal}\label{wxdialogismodal}

 
 

-\wxheading{Remarks}
+\constfunc{bool}{IsModal}{\void}

 
 

-This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}.
+Returns true if the dialog box is modal, false otherwise.

 
 

-\wxheading{See also}

 
 

-\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel}

 
 

-\membersection{wxDialog::OnCancel}\label{wxdialogoncancel}
+\membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged}

 
 

-\func{void}{OnCancel}{\param{wxCommandEvent\& }{event}}
+\func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}}

 
 

-The default handler for the wxID\_CANCEL identifier.
+The default handler for wxEVT\_SYS\_COLOUR\_CHANGED.
+
+\wxheading{Parameters}
+
+\docparam{event}{The colour change event.}

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-The function either calls {\bf EndModal(wxID\_CANCEL)} if the dialog is modal, or
-sets the return value to wxID\_CANCEL and calls {\bf Show(false)} if the dialog is modeless.
+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.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnApply}{wxdialogonapply}
+\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}
+

 
 

-\membersection{wxDialog::OnOK}\label{wxdialogonok}
+\membersection{wxDialog::SetAffirmativeId}\label{wxdialogsetaffirmativeid}

 
 

-\func{void}{OnOK}{\param{wxCommandEvent\& }{event}}
+\func{void}{SetAffirmativeId}{\param{int }{id}}

 
 

-The default handler for the wxID\_OK identifier.
+Sets the identifier to be used as OK button. When the button with this
+identifier is pressed, the dialog calls \helpref{Validate}{wxwindowvalidate} 
+and \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow} 
+and, if they both return \true, closes the dialog with \texttt{wxID\_OK} return
+code.

 
 

-\wxheading{Remarks}
+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.

 
 

-The function calls
-\rtfsp\helpref{wxWindow::Validate}{wxwindowvalidate}, then \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}.
-If this returns true, the function either calls {\bf EndModal(wxID\_OK)} if the dialog is modal, or
-sets the return value to wxID\_OK and calls {\bf Show(false)} if the dialog is modeless.
+By default, the affirmative id is wxID\_OK.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply}
+\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid}, \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid}

 
 

-\membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged}

 
 

-\func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}}
+\membersection{wxDialog::SetEscapeId}\label{wxdialogsetescapeid}

 
 

-The default handler for wxEVT\_SYS\_COLOUR\_CHANGED.
+\func{void}{SetEscapeId}{\param{int }{id}}

 
 

-\wxheading{Parameters}
+Sets the identifier of the button which should work like the standard 
+\texttt{\textsc{Cancel}} button in this dialog. When the button with this id is
+clicked, the dialog is closed. Also, when the user presses \texttt{\textsc{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.

 
 

-\docparam{event}{The colour change event.}
+By default, the escape id is the special value \texttt{wxID\_ANY} meaning that 
+\texttt{wxID\_CANCEL} button is used if it's present in the dialog and
+otherwise the button with \helpref{GetAffirmativeId()}{wxdialoggetaffirmativeid} 
+is used. Another special value for \arg{id} is \texttt{wxID\_NONE} meaning that
+\texttt{\textsc{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.

 
 

-\wxheading{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.
-
-\wxheading{See also}
-
-\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}

 
 \membersection{wxDialog::SetIcon}\label{wxdialogseticon}
 
 
 \membersection{wxDialog::SetIcon}\label{wxdialogseticon}
 


@@ -330,6 +533,7 @@ Sets the icon for this dialog.
 
 See also \helpref{wxIcon}{wxicon}.
 
 
 See also \helpref{wxIcon}{wxicon}.
 

+

 \membersection{wxDialog::SetIcons}\label{wxdialogseticons}
 
 \func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}
 \membersection{wxDialog::SetIcons}\label{wxdialogseticons}
 
 \func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}


@@ -342,11 +546,59 @@ Sets the icons for this dialog.
 
 See also \helpref{wxIconBundle}{wxiconbundle}.
 
 
 See also \helpref{wxIconBundle}{wxiconbundle}.
 

+
+\membersection{wxDialog::SetLayoutAdaptationDone}\label{wxdialogsetlayoutadaptationdone}
+
+\func{void}{SetLayoutAdaptationDone}{\param{bool }{done}}
+
+Marks the dialog as having been adapted, usually by making it scrollable to work with a small display.
+
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+
+
+\membersection{wxDialog::SetLayoutAdaptationLevel}\label{wxdialogsetlayoutadaptationlevel}
+
+\func{void}{SetLayoutAdaptationLevel}{\param{int }{level}}
+
+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 \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+
+
+\membersection{wxDialog::SetLayoutAdaptationMode}\label{wxdialogsetlayoutadaptationmode}
+
+\func{void}{SetLayoutAdaptationMode}{\param{wxDialogLayoutAdaptationMode }{mode}}
+
+Sets the adaptation mode, overriding the global adaptation flag. {\it mode} may be one of the following values:
+
+\begin{verbatim}
+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
+};
+\end{verbatim}
+
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.
+
+
+\membersection{wxDialog::SetLayoutAdapter}\label{wxdialogsetlayoutadapter}
+
+\func{static wxDialogLayoutAdapter*}{SetLayoutAdapter}{\param{wxDialogLayoutAdapter*}{ adapter}}
+
+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 \helpref{wxDialogLayoutAdapter}{wxdialoglayoutadapter} and \helpref{Automatic scrolling dialogs}{autoscrollingdialogs}.
+
+

 \membersection{wxDialog::SetModal}\label{wxdialogsetmodal}
 
 \membersection{wxDialog::SetModal}\label{wxdialogsetmodal}
 

-\func{void}{SetModal}{\param{const bool}{ flag}}
+\func{void}{SetModal}{\param{bool}{ flag}}

 
 

-{\bf NB:} This function is deprecated and doesn't work for all ports, just use 
+{\bf NB:} This function is deprecated and doesn't work for all ports, just use

 \helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead.
 
 Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control
 \helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead.
 
 Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control


@@ -356,6 +608,7 @@ until the dialog is hidden) or modeless (control returns immediately).
 
 \docparam{flag}{If true, the dialog will be modal, otherwise it will be modeless.}
 
 
 \docparam{flag}{If true, the dialog will be modal, otherwise it will be modeless.}
 

+

 \membersection{wxDialog::SetReturnCode}\label{wxdialogsetreturncode}
 
 \func{void}{SetReturnCode}{\param{int }{retCode}}
 \membersection{wxDialog::SetReturnCode}\label{wxdialogsetreturncode}
 
 \func{void}{SetReturnCode}{\param{int }{retCode}}


@@ -376,19 +629,10 @@ a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogend
 \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 
 \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 

-\membersection{wxDialog::SetTitle}\label{wxdialogsettitle}
-
-\func{void}{SetTitle}{\param{const wxString\& }{ title}}
-
-Sets the title of the dialog box.
-
-\wxheading{Parameters}
-
-\docparam{title}{The dialog box title.}

 
 \membersection{wxDialog::Show}\label{wxdialogshow}
 
 
 \membersection{wxDialog::Show}\label{wxdialogshow}
 

-\func{bool}{Show}{\param{const bool}{ show}}
+\func{bool}{Show}{\param{bool}{ show}}

 
 Hides or shows the dialog.
 
 
 Hides or shows the dialog.
 


@@ -402,6 +646,7 @@ modal, control is returned to the calling program.}
 
 The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}.
 
 
 The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}.
 

+

 \membersection{wxDialog::ShowModal}\label{wxdialogshowmodal}
 
 \func{int}{ShowModal}{\void}
 \membersection{wxDialog::ShowModal}\label{wxdialogshowmodal}
 
 \func{int}{ShowModal}{\void}