X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2edb0bdef6238c8c246b6978bc14828b7033d931..2c6f14e1a7b5062fcf77eda40824d820d9ac288e:/docs/latex/wx/dialog.tex

diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex
index 7084957d80..2c856f35bc 100644
--- a/docs/latex/wx/dialog.tex
+++ b/docs/latex/wx/dialog.tex
@@ -1,11 +1,11 @@
 \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 usually used to allow the user to make some choice or to answer a question.
 
 \wxheading{Derived from}
 
-\helpref{wxPanel}{wxpanel}\\
 \helpref{wxWindow}{wxwindow}\\
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
@@ -16,29 +16,53 @@ the screen. It can contain controls and other windows.
 
 \wxheading{Remarks}
 
-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.
-
-A dialog may be loaded from a wxWindows resource file (extension {\tt wxr}), which may itself
-be created by Dialog Editor. For details,
-see \helpref{The wxWindows resource system}{resourceformats}, \helpref{wxWindows resource functions}{resourcefuncs} and
-the resource sample.
-
-An application can define an \helpref{wxCloseEvent}{wxcloseevent} handler for the
-dialog to respond to system close events.
+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. To show a modal dialog
+you should use \helpref{ShowModal}{wxdialogshowmodal} method while to show
+dialog modelessly you simply use \helpref{Show}{wxdialogshow}, just as with the
+frames.
+
+Note that the modal dialogs are 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
+
+        dlg->Destroy();
+    }
+\end{verbatim}
+works, you can also achieve the same result by using a simpler code fragment
+below:
+\begin{verbatim}
+    void AskUser()
+    {
+        MyAskDialog dlg(...);
+        if ( dlg.ShowModal() == wxID_OK )
+            ...
+
+        // no need to call Destroy() here
+    }
+\end{verbatim}
+
+An application can define an \helpref{wxCloseEvent}{wxcloseevent} handler for
+the dialog to respond to system close events.
 
 \wxheading{Window styles}
 
 \twocolwidtha{5cm}
 \begin{twocollist}\itemsep=0pt
-\twocolitem{\windowstyle{wxDIALOG\_MODAL}}{Specifies that the dialog box will be modal.}
 \twocolitem{\windowstyle{wxCAPTION}}{Puts a caption on the dialog box.}
-\twocolitem{\windowstyle{wxDEFAULT\_DIALOG\_STYLE}}{Equivalent to a combination of wxCAPTION, wxSYSTEM\_MENU and wxTHICK\_FRAME}
+\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{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{wxNO\_3D}}{Under Windows, specifies that the child controls
@@ -50,7 +74,7 @@ style to prevent this from happening and create a really orphan dialog (note
 that 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 wxWindows will send
-a wxEVT\_HELP event if the user clicked on an application window. {\it Note} that this is an extended
+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).}
 \end{twocollist}
 
@@ -62,7 +86,7 @@ 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}}}
@@ -181,31 +205,31 @@ Iconizes or restores the dialog. Windows only.
 
 \wxheading{Parameters}
 
-\docparam{iconize}{If TRUE, iconizes the dialog box; if FALSE, shows and restores it.}
+\docparam{iconize}{If true, iconizes the dialog box; if false, shows and restores it.}
 
 \wxheading{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 {\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}
 
-Returns TRUE if the dialog box is iconized. Windows only.
+Returns true if the dialog box is iconized. Windows only.
 
 \wxheading{Remarks}
 
-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}
 
-Returns TRUE if the dialog box is modal, FALSE otherwise.
+Returns true if the dialog box is modal, false otherwise.
 
 \membersection{wxDialog::OnCharHook}\label{wxdialogoncharhook}
 
@@ -244,7 +268,7 @@ 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.
+sets the return value to wxID\_CANCEL and calls {\bf Show(false)} if the dialog is modeless.
 
 \wxheading{See also}
 
@@ -260,8 +284,8 @@ The default handler for the wxID\_OK identifier.
 
 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.
+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}
 
@@ -325,7 +349,7 @@ 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::SetReturnCode}\label{wxdialogsetreturncode}
 
@@ -365,8 +389,8 @@ 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}