Applied patch [ 589484 ] wxGenericListCtrl, fix for direct use.

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

diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex
index 95d758c852066344421c20403e5e2786f15a9d39..7084957d801b6b550238924091bbd05818e2ccea 100644 (file)
--- a/docs/latex/wx/dialog.tex
+++ b/docs/latex/wx/dialog.tex
@@ -10,6 +10,10 @@ the screen. It can contain controls and other windows.
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 

+\wxheading{Include files}
+
+<wx/dialog.h>
+

 \wxheading{Remarks}
 
 There are two kinds of dialog - {\it modal} and {\it modeless}. A modal dialog
 \wxheading{Remarks}
 
 There are two kinds of dialog - {\it modal} and {\it modeless}. A modal dialog


@@ -18,26 +22,41 @@ like a frame in that program flow continues, and input on other windows is still
 You specify the type of dialog with the {\bf wxDIALOG\_MODAL} and {\bf wxDIALOG\_MODELESS} window
 styles.
 
 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}).
+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
+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
 dialog to respond to system close events.
 
 \wxheading{Window styles}
 
 \twocolwidtha{5cm}
 \begin{twocollist}\itemsep=0pt

-\twocolitem{\windowstyle{wxCAPTION}}{Puts a caption on the dialog box (Motif only).}
+\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, wxSYSTEM\_MENU and wxTHICK\_FRAME}

-\twocolitem{\windowstyle{wxRESIZE\_BORDER}}{Display a resizeable frame around the window (Motif only).}
+\twocolitem{\windowstyle{wxRESIZE\_BORDER}}{Display a resizeable frame around the window.}

 \twocolitem{\windowstyle{wxSYSTEM\_MENU}}{Display a system menu.}
 \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{wxSYSTEM\_MENU}}{Display a system menu.}
 \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, the dialogs created
+with {\tt NULL} parent window will be given the 
+\helpref{applications top level window}{wxappgettopwindow} as parent. Use this
+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
+style and must be set by calling \helpref{SetExtraStyle}{wxwindowsetextrastyle} before Create is called (two-step construction).}

 \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}.
 
 
 See also \helpref{Generic window styles}{windowstyles}.
 


@@ -129,8 +148,24 @@ 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::GetReturnCode}\label{wxdialoggetreturncode}
+
+\func{int}{GetReturnCode}{\void}
+
+Gets the return code for this window.
+
+\wxheading{Remarks}
+
+A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
+a code to the application.
+
+\wxheading{See also}
+
+\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
+\helpref{wxDialog::EndModal}{wxdialogendmodal}

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


@@ -142,7 +177,7 @@ Returns the title of the dialog box.
 
 \func{void}{Iconize}{\param{const bool}{ iconize}}
 
 
 \func{void}{Iconize}{\param{const bool}{ iconize}}
 

-Iconizes or restores the dialog.
+Iconizes or restores the dialog. Windows only.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -160,7 +195,7 @@ calling {\tt Iconize(FALSE)} will bring the window to the front, as does
 
 \constfunc{bool}{IsIconized}{\void}
 
 
 \constfunc{bool}{IsIconized}{\void}
 

-Returns TRUE if the dialog box is iconized.
+Returns TRUE if the dialog box is iconized. Windows only.

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 


@@ -179,7 +214,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}
 


@@ -247,17 +282,44 @@ 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}}
 

+{\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).
 
 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).
 


@@ -265,6 +327,26 @@ until the dialog is hidden) or modeless (control returns immediately).
 
 \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}
+
+\func{void}{SetReturnCode}{\param{int }{retCode}}
+
+Sets the return code for this window.
+
+\wxheading{Parameters}
+
+\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::SetTitle}\label{wxdialogsettitle}
 
 \func{void}{SetTitle}{\param{const wxString\& }{ title}}
 \membersection{wxDialog::SetTitle}\label{wxdialogsettitle}
 
 \func{void}{SetTitle}{\param{const wxString\& }{ title}}


@@ -300,12 +382,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}