escape more underscores (we need a pre-commit check for those...)

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

diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex
index 4107a0136216ea0a05a0b3da5ea153f71f456411..6e9e17d8b4e1bf71f3586bb7845356452c3614c6 100644 (file)
--- a/docs/latex/wx/dialog.tex
+++ b/docs/latex/wx/dialog.tex
@@ -1,3 +1,14 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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
 \section{\class{wxDialog}}\label{wxdialog}
 
 A dialog box is a window with a title bar and sometimes a system menu, which


@@ -74,7 +85,7 @@ the dialog to respond to system close events.
 \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
 \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


@@ -178,7 +189,23 @@ of the following flags: wxOK, wxCANCEL, wxYES, wxNO, 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 simply calls \helpref{CreateStdDialogButtonSizer}{wxdialogcreatestddialogbuttonsizer}.
+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}
 
 
 \membersection{wxDialog::CreateStdDialogButtonSizer}\label{wxdialogcreatestddialogbuttonsizer}


@@ -223,7 +250,8 @@ invocation.
 
 \constfunc{int}{GetAffirmativeId}{\void}
 
 
 \constfunc{int}{GetAffirmativeId}{\void}
 

-Gets the identifier to be used when the user presses an OK button in a PocketPC titlebar.
+Gets the identifier of the button which works like standard OK button in this
+dialog.

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


@@ -259,13 +287,6 @@ a code to the application.
 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 
 
 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 
 

-\membersection{wxDialog::GetTitle}\label{wxdialoggettitle}
-
-\constfunc{wxString}{GetTitle}{\void}
-
-Returns the title of the dialog box.
-
-

 \membersection{wxDialog::GetToolBar}\label{wxdialoggettoolbar}
 
 \constfunc{wxToolBar*}{GetToolBar}{\void}
 \membersection{wxDialog::GetToolBar}\label{wxdialoggettoolbar}
 
 \constfunc{wxToolBar*}{GetToolBar}{\void}


@@ -322,7 +343,7 @@ The default handler for the wxID\_APPLY identifier.
 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}.
+This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}.

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


@@ -390,24 +411,38 @@ propagate the notification to child windows and controls.
 
 \func{void}{SetAffirmativeId}{\param{int }{id}}
 
 
 \func{void}{SetAffirmativeId}{\param{int }{id}}
 

-Sets the identifier to be used when the user presses an OK button in a PocketPC titlebar.
-By default, this is wxID\_OK.
+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}
 
 
 \wxheading{See also}
 

-\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid}
+\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid}, \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid}

 
 
 \membersection{wxDialog::SetEscapeId}\label{wxdialogsetescapeid}
 
 \func{void}{SetEscapeId}{\param{int }{id}}
 
 
 
 \membersection{wxDialog::SetEscapeId}\label{wxdialogsetescapeid}
 
 \func{void}{SetEscapeId}{\param{int }{id}}
 

-Sets the identifier to be used when the user presses \texttt{\textsc{ESC}}
-button in the dialog. By default, this is \texttt{wxID\_ANY} meaning that
-the first suitable button is used: if there a \texttt{wxID\_CANCEL} button, it
-is activated, otherwise \texttt{wxID\_OK} button is activated if present.
-Another possible special value for \arg{id} is \texttt{wxID\_NONE} meaning that
-\texttt{\textsc{ESC}} presses should be ignored. If another value is given, it
+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.
 
 
 is interpreted as the id of the button to map the escape key to.
 
 


@@ -441,7 +476,7 @@ See also \helpref{wxIconBundle}{wxiconbundle}.
 
 \func{void}{SetModal}{\param{const bool}{ flag}}
 
 
 \func{void}{SetModal}{\param{const 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


@@ -473,17 +508,6 @@ a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogend
 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 
 
 \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}
 
 \func{bool}{Show}{\param{const bool}{ show}}
 \membersection{wxDialog::Show}\label{wxdialogshow}
 
 \func{bool}{Show}{\param{const bool}{ show}}


@@ -517,4 +541,3 @@ The return value is the value set with \helpref{wxDialog::SetReturnCode}{wxdialo
 \helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
 \helpref{wxDialog:GetReturnCode}{wxdialoggetreturncode},\rtfsp
 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
 \helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
 \helpref{wxDialog:GetReturnCode}{wxdialoggetreturncode},\rtfsp
 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}

-