remove C++ comment

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

diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex
index c65b41d41c8525369441c9a7ed8f6c9994fd4ae5..31818d2c9bebadee9b9758cc2ae8f5c752a0bcad 100644 (file)
--- a/docs/latex/wx/dialog.tex
+++ b/docs/latex/wx/dialog.tex
@@ -1,53 +1,137 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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}
 
 \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.
+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.
+
+
+\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}
 

-\helpref{wxPanel}{wxpanel}\\
+\helpref{wxTopLevelWindow}{wxtoplevelwindow}\\

 \helpref{wxWindow}{wxwindow}\\
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 
 \helpref{wxWindow}{wxwindow}\\
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 

-\wxheading{Remarks}
+\wxheading{Include files}
+
+<wx/dialog.h>
+
+\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,
+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 \helpref{ShowModal}{wxdialogshowmodal} method while to show
+a dialog modelessly you simply use \helpref{Show}{wxdialogshow}, 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, although this code snippet:
+
+\begin{verbatim}
+    void AskUser()
+    {
+        MyAskDialog *dlg = new MyAskDialog(...);
+        if ( dlg->ShowModal() == wxID_OK )
+            ...
+        //else: dialog was cancelled or some another button pressed

 
 

-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, whereas a modeless dialog behaves more
-like a frame in that program flow continues, and input on other windows is still possible.
-You specify the type of dialog with the {\bf wxDIALOG\_MODAL} and {\bf wxDIALOG\_MODELESS} window
-styles.
+        dlg->Destroy();
+    }
+\end{verbatim}

 
 

-A dialog may be loaded from a wxWindows resource file (extension {\tt wxr}).
+works, you can also achieve the same result by using a simpler code fragment
+below:

 
 

-An application can define an \helpref{OnCloseWindow}{wxwindowonclosewindow} handler for the
-dialog to respond to system close events.
+\begin{verbatim}
+    void AskUser()
+    {
+        MyAskDialog dlg(...);
+        if ( dlg.ShowModal() == wxID_OK )
+            ...
+
+        // no need to call Destroy() here
+    }
+\end{verbatim}
+
+An application can define a \helpref{wxCloseEvent}{wxcloseevent} handler for
+the dialog to respond to system close events.

 
 \wxheading{Window styles}
 
 \twocolwidtha{5cm}
 \begin{twocollist}\itemsep=0pt
 
 \wxheading{Window styles}
 
 \twocolwidtha{5cm}
 \begin{twocollist}\itemsep=0pt

-\twocolitem{\windowstyle{wxCAPTION}}{Puts a caption on the dialog box (Motif only).}
-\twocolitem{\windowstyle{wxDEFAULT\_DIALOG\_STYLE}}{Equivalent to a combination of wxCAPTION, wxSYSTEM\_MENU and wxTHICK\_FRAME}
-\twocolitem{\windowstyle{wxRESIZE\_BORDER}}{Display a resizeable frame around the window (Motif only).}
-\twocolitem{\windowstyle{wxSYSTEM\_MENU}}{Display a system menu (Motif only).}
-\twocolitem{\windowstyle{wxTHICK\_FRAME}}{Display a thick frame around the window (Motif only).}
+\twocolitem{\windowstyle{wxCAPTION}}{Puts a caption on the dialog box.}
+\twocolitem{\windowstyle{wxDEFAULT\_DIALOG\_STYLE}}{Equivalent to a combination of wxCAPTION, wxCLOSE\_BOX and wxSYSTEM\_MENU (the last one is not used under Unix)}
+\twocolitem{\windowstyle{wxRESIZE\_BORDER}}{Display a resizeable frame around the window.}
+\twocolitem{\windowstyle{wxSYSTEM\_MENU}}{Display a system menu.}
+\twocolitem{\windowstyle{wxCLOSE\_BOX}}{Displays a close box on the frame.}
+\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.}

 \twocolitem{\windowstyle{wxNO\_3D}}{Under Windows, specifies that the child controls
 should not have 3D borders unless specified in the control.}
 \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
+\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}
 
 \end{twocollist}
 

-Under Motif, MWM (the Motif Window Manager) should be running for any of these styles to have an effect.
+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.

 
 See also \helpref{Generic window styles}{windowstyles}.
 
 \wxheading{See also}
 
 
 See also \helpref{Generic window styles}{windowstyles}.
 
 \wxheading{See also}
 

-\helpref{wxDialog overview}{wxdialogoverview}, \helpref{wxFrame}{wxframe}, \helpref{Resources}{resources},\rtfsp
+\helpref{wxDialog overview}{wxdialogoverview}, \helpref{wxFrame}{wxframe},\rtfsp

 \helpref{Validator overview}{validatoroverview}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \helpref{Validator overview}{validatoroverview}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxDialog::wxDialog}\label{wxdialogconstr}
+
+\membersection{wxDialog::wxDialog}\label{wxdialogctor}

 
 \func{}{wxDialog}{\void}
 
 
 \func{}{wxDialog}{\void}
 


@@ -71,10 +155,10 @@ Constructor.
 \docparam{title}{The title of the dialog.}
 
 \docparam{pos}{The dialog position. A value of (-1, -1) indicates a default position, chosen by
 \docparam{title}{The title of the dialog.}
 
 \docparam{pos}{The dialog position. A value of (-1, -1) indicates a default position, chosen by

-either the windowing system or wxWindows, depending on platform.}
+either the windowing system or wxWidgets, depending on platform.}

 
 \docparam{size}{The dialog size. A value of (-1, -1) indicates a default size, chosen by
 
 \docparam{size}{The dialog size. A value of (-1, -1) indicates a default size, chosen by

-either the windowing system or wxWindows, depending on platform.}
+either the windowing system or wxWidgets, depending on platform.}

 
 \docparam{style}{The window style. See \helpref{wxDialog}{wxdialog}.}
 
 
 \docparam{style}{The window style. See \helpref{wxDialog}{wxdialog}.}
 


@@ -86,12 +170,14 @@ individual dialog boxes.}
 
 \helpref{wxDialog::Create}{wxdialogcreate}
 
 
 \helpref{wxDialog::Create}{wxdialogcreate}
 

-\membersection{wxDialog::\destruct{wxDialog}}
+
+\membersection{wxDialog::\destruct{wxDialog}}\label{wxdialogdtor}

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

+

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


@@ -102,6 +188,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


@@ -111,9 +198,60 @@ Centres the dialog box on the display.
 \param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp
 \param{const wxString\& }{name = ``dialogBox"}}
 
 \param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp
 \param{const wxString\& }{name = ``dialogBox"}}
 

-Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogconstr}\rtfsp
+Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogctor}\rtfsp

 for details.
 
 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::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::EndModal}\label{wxdialogendmodal}
 
 \func{void}{EndModal}{\param{int }{retCode}}
 \membersection{wxDialog::EndModal}\label{wxdialogendmodal}
 
 \func{void}{EndModal}{\param{int }{retCode}}


@@ -128,108 +266,99 @@ invocation.
 \wxheading{See also}
 
 \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 \wxheading{See also}
 
 \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp

-\helpref{wxWindow::GetReturnCode}{wxwindowgetreturncode},\rtfsp
-\helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}
+\helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp
+\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}

 
 

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

 
 

-\constfunc{wxString}{GetTitle}{\void}
+\membersection{wxDialog::GetAffirmativeId}\label{wxdialoggetaffirmativeid}

 
 

-Returns the title of the dialog box.
+\constfunc{int}{GetAffirmativeId}{\void}

 
 

-\membersection{wxDialog::Iconize}\label{wxdialogiconized}
+Gets the identifier of the button which works like standard OK button in this
+dialog.

 
 

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

 
 

-Iconizes or restores the dialog.
+\helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid}

 
 

-\wxheading{Parameters}

 
 

-\docparam{iconize}{If TRUE, iconizes the dialog box; if FALSE, shows and restores it.}
+\membersection{wxDialog::GetEscapeId}\label{wxdialoggetescapeid}

 
 

-\wxheading{Remarks}
+\constfunc{int}{GetEscapeId}{\void}

 
 

-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 {\tt Iconize(FALSE)} will bring the window to the front, as does
-\rtfsp{\tt Show(TRUE)}.
+Gets the identifier of the button to map presses of \texttt{\textsc{ESC}}
+button to.

 
 

-\membersection{wxDialog::IsIconized}\label{wxdialogisiconized}
+\wxheading{See also}

 
 

-\constfunc{bool}{IsIconized}{\void}
+\helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid}

 
 

-Returns TRUE if the dialog box is iconized.

 
 

-\wxheading{Remarks}
+\membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode}

 
 

-Always returns FALSE under Windows since dialogs cannot be iconized.
+\func{int}{GetReturnCode}{\void}

 
 

-\membersection{wxDialog::IsModal}\label{wxdialogismodal}
+Gets the return code for this window.

 
 

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

 
 

-Returns TRUE if the dialog box is modal, FALSE otherwise.
+A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
+a code to the application.

 
 

-\membersection{wxDialog::OnCharHook}\label{wxdialogoncharhook}
+\wxheading{See also}

 
 

-\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}
+\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
+\helpref{wxDialog::EndModal}{wxdialogendmodal}

 
 

-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::GetToolBar}\label{wxdialoggettoolbar}

 
 

-\wxheading{Remarks}
+\constfunc{wxToolBar*}{GetToolBar}{\void}

 
 

-wxDialog implements this handler to fake a cancel command if the escape key has been
-pressed. This will dismiss the dialog.
+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.

 
 

-\membersection{wxDialog::OnApply}\label{wxdialogonapply}
+This function is not available on any other platform.

 
 

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

 
 

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

 
 

-\wxheading{Remarks}
+\func{void}{Iconize}{\param{bool}{ iconize}}

 
 

-This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}.
+Iconizes or restores the dialog. Windows only.

 
 

-\wxheading{See also}
+\wxheading{Parameters}

 
 

-\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel}
+\docparam{iconize}{If true, iconizes the dialog box; if false, shows and restores it.}

 
 

-\membersection{wxDialog::OnCancel}\label{wxdialogoncancel}
+\wxheading{Remarks}

 
 

-\func{void}{OnCancel}{\param{wxCommandEvent\& }{event}}
+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 {\tt Iconize(false)} will bring the window to the front, as does
+\rtfsp{\tt Show(true)}.

 
 

-The default handler for the wxID\_CANCEL identifier.

 
 

-\wxheading{Remarks}
+\membersection{wxDialog::IsIconized}\label{wxdialogisiconized}

 
 

-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.
+\constfunc{bool}{IsIconized}{\void}

 
 

-\wxheading{See also}
+Returns true if the dialog box is iconized. Windows only.

 
 

-\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnApply}{wxdialogonapply}
+\wxheading{Remarks}

 
 

-\membersection{wxDialog::OnOK}\label{wxdialogonok}
+Always returns false under Windows since dialogs cannot be iconized.

 
 

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

 
 

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

 
 

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

 
 

-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.
+Returns true if the dialog box is modal, false otherwise.

 
 

-\wxheading{See also}

 
 

-\helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply}

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


@@ -246,50 +375,132 @@ The default handler for wxEVT\_SYS\_COLOUR\_CHANGED.
 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
 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 \helpref{wxWindow::OnSysColourChanged}{wxwindowonsyscolourchanged} to
+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}
 
 propagate the notification to child windows and controls.
 
 \wxheading{See also}
 
 \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}
 

+
+\membersection{wxDialog::SetAffirmativeId}\label{wxdialogsetaffirmativeid}
+
+\func{void}{SetAffirmativeId}{\param{int }{id}}
+
+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.
+
+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.
+
+\wxheading{See also}
+
+\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid}, \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid}
+
+
+\membersection{wxDialog::SetEscapeId}\label{wxdialogsetescapeid}
+
+\func{void}{SetEscapeId}{\param{int }{id}}
+
+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.
+
+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.
+
+
+\membersection{wxDialog::SetIcon}\label{wxdialogseticon}
+
+\func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
+
+Sets the icon for this dialog.
+
+\wxheading{Parameters}
+
+\docparam{icon}{The icon to associate with this dialog.}
+
+See also \helpref{wxIcon}{wxicon}.
+
+
+\membersection{wxDialog::SetIcons}\label{wxdialogseticons}
+
+\func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}
+
+Sets the icons for this dialog.
+
+\wxheading{Parameters}
+
+\docparam{icons}{The icons to associate with this dialog.}
+
+See also \helpref{wxIconBundle}{wxiconbundle}.
+
+

 \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
+\helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead.

 
 Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control
 until the dialog is hidden) or modeless (control returns immediately).
 
 \wxheading{Parameters}
 
 
 Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control
 until the dialog is hidden) or modeless (control returns immediately).
 
 \wxheading{Parameters}
 

-\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::SetTitle}\label{wxdialogsettitle}

 
 

-\func{void}{SetTitle}{\param{const wxString\& }{ title}}
+\membersection{wxDialog::SetReturnCode}\label{wxdialogsetreturncode}

 
 

-Sets the title of the dialog box.
+\func{void}{SetReturnCode}{\param{int }{retCode}}
+
+Sets the return code for this window.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 

-\docparam{title}{The dialog box title.}
+\docparam{retCode}{The integer return code, usually a control identifier.}
+
+\wxheading{Remarks}
+
+A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
+a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogendmodal} calls {\bf SetReturnCode}.
+
+\wxheading{See also}
+
+\helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
+\helpref{wxDialog::EndModal}{wxdialogendmodal}
+

 
 \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.
 
 \wxheading{Parameters}
 
 
 Hides or shows the dialog.
 
 \wxheading{Parameters}
 

-\docparam{show}{If TRUE, the dialog box is shown and brought to the front;
-otherwise the box is hidden. If FALSE and the dialog is
+\docparam{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.}
 
 \wxheading{Remarks}
 
 The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}.
 
 modal, control is returned to the calling program.}
 
 \wxheading{Remarks}
 
 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}


@@ -299,12 +510,11 @@ Shows a modal dialog. Program flow does not return until the dialog has been dis
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-The return value is the value set with \helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}.
+The return value is the value set with \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}.

 
 \wxheading{See also}
 
 \helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
 
 \wxheading{See also}
 
 \helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp

-\helpref{wxWindow::GetReturnCode}{wxwindowgetreturncode},\rtfsp
-\helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}
-
+\helpref{wxDialog:GetReturnCode}{wxdialoggetreturncode},\rtfsp
+\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}