support for huge files (patch 1002226)

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

diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex
index 0ea060871c97a892f6c22b4ba40a2ae175435dee..de31dae46ffee9f6332ccbfcf774b3fdae097909 100644 (file)
--- a/docs/latex/wx/dialog.tex
+++ b/docs/latex/wx/dialog.tex
@@ -1,11 +1,12 @@
 \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 usually used to allow the user to make some choice or to answer a question.

 
 \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}


@@ -16,43 +17,81 @@ the screen. It can contain controls and other windows.
 
 \wxheading{Remarks}
 
 
 \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{OnCloseWindow}{wxwindowonclosewindow} 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 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
+
+        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
 
 \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{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{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 (Windows only).}
 \twocolitem{\windowstyle{wxNO\_3D}}{Under Windows, specifies that the child controls
 should not have 3D borders unless specified in the control.}
 \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
 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).}

 \end{twocollist}
 
 \end{twocollist}
 

-Under Unix or Linux, MWM (the Motif Window Manager) or other window managers reckognizing
-the MHM hints 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}}}


@@ -81,10 +120,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}.}
 


@@ -171,31 +210,31 @@ Iconizes or restores the dialog. Windows only.
 
 \wxheading{Parameters}
 
 
 \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
 
 \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}
 
 
 \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}
 
 
 \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}
 
 
 \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}
 
 
 \membersection{wxDialog::OnCharHook}\label{wxdialogoncharhook}
 


@@ -204,7 +243,7 @@ Returns TRUE if the dialog box is modal, FALSE otherwise.
 This member is called to allow the window to intercept keyboard events
 before they are processed by child windows.
 
 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}
+%For more information, see \helpref{wxWindow::OnCharHook}{wxwindowoncharhook}

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 


@@ -234,7 +273,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
 \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}
 
 
 \wxheading{See also}
 


@@ -250,8 +289,8 @@ The default handler for the wxID\_OK identifier.
 
 The function calls
 \rtfsp\helpref{wxWindow::Validate}{wxwindowvalidate}, then \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}.
 
 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}
 
 
 \wxheading{See also}
 


@@ -272,13 +311,37 @@ 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::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}
 
 \func{void}{SetModal}{\param{const bool}{ flag}}
 \membersection{wxDialog::SetModal}\label{wxdialogsetmodal}
 
 \func{void}{SetModal}{\param{const bool}{ flag}}


@@ -291,7 +354,7 @@ until the dialog is hidden) or modeless (control returns immediately).
 
 \wxheading{Parameters}
 
 
 \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}
 
 
 \membersection{wxDialog::SetReturnCode}\label{wxdialogsetreturncode}
 


@@ -331,8 +394,8 @@ Hides or shows the dialog.
 
 \wxheading{Parameters}
 
 
 \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}
 modal, control is returned to the calling program.}
 
 \wxheading{Remarks}