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 1ab082deeb4713cfaa822e11f988a29640eb7b78..31818d2c9bebadee9b9758cc2ae8f5c752a0bcad 100644 (file)
--- a/docs/latex/wx/dialog.tex
+++ b/docs/latex/wx/dialog.tex
@@ -13,7 +13,25 @@
 
 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
 
 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.
+
+
+\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}
 


@@ -26,7 +44,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,


@@ -185,11 +207,28 @@ for details.
 \func{wxSizer*}{CreateButtonSizer}{\param{long}{ flags}}
 
 Creates a sizer with standard buttons. {\it flags} is a bit list
 \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, wxHELP, wxNO\_DEFAULT.
+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 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}


@@ -197,7 +236,8 @@ This function simply calls \helpref{CreateStdDialogButtonSizer}{wxdialogcreatest
 \func{wxStdDialogButtonSizer*}{CreateStdDialogButtonSizer}{\param{long}{ flags}}
 
 Creates a \helpref{wxStdDialogButtonSizer}{wxstddialogbuttonsizer} with standard buttons. {\it flags} is a bit list
 \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, wxHELP, wxNO\_DEFAULT.
+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.
 


@@ -234,7 +274,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}
 


@@ -283,7 +324,7 @@ This function is not available on any other platform.
 
 \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.
 


@@ -318,54 +359,6 @@ Always returns false under Windows since dialogs cannot be iconized.
 Returns true if the dialog box is modal, false otherwise.
 
 
 Returns true if the dialog box is modal, false otherwise.
 
 

-\membersection{wxDialog::OnApply}\label{wxdialogonapply}
-
-\func{void}{OnApply}{\param{wxCommandEvent\& }{event}}
-
-The default handler for the wxID\_APPLY identifier.
-
-\wxheading{Remarks}
-
-This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}.
-
-\wxheading{See also}
-
-\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel}
-
-
-\membersection{wxDialog::OnCancel}\label{wxdialogoncancel}
-
-\func{void}{OnCancel}{\param{wxCommandEvent\& }{event}}
-
-The default handler for the wxID\_CANCEL identifier.
-
-\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.
-
-\wxheading{See also}
-
-\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnApply}{wxdialogonapply}
-
-
-\membersection{wxDialog::OnOK}\label{wxdialogonok}
-
-\func{void}{OnOK}{\param{wxCommandEvent\& }{event}}
-
-The default handler for the wxID\_OK identifier.
-
-\wxheading{Remarks}
-
-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.
-
-\wxheading{See also}
-
-\helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply}
-

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


@@ -394,24 +387,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.
 
 


@@ -443,7 +450,7 @@ 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.
 
 {\bf NB:} This function is deprecated and doesn't work for all ports, just use
 \helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead.


@@ -479,7 +486,7 @@ a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogend
 
 \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.
 


@@ -510,3 +517,4 @@ 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}

+