X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f4fcc2919776cffa5e3b2f0d44dd24c41e652ff4..1a87edf286921de9b182f3d19adb6bb63ba85ebd:/docs/latex/wx/dialog.tex?ds=sidebyside diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex index 6c3de31f29..7423e38860 100644 --- a/docs/latex/wx/dialog.tex +++ b/docs/latex/wx/dialog.tex @@ -1,11 +1,12 @@ \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{wxTopLevelWindow}{wxtoplevelwindow}\\ \helpref{wxWindow}{wxwindow}\\ \helpref{wxEvtHandler}{wxevthandler}\\ \helpref{wxObject}{wxobject} @@ -16,58 +17,86 @@ 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 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 a \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{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{wxDIALOG\_NO\_PARENT}}{By default, the dialogs crated -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\_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 wxWindows will send -a wxEVT\_HELP event if the user clicked on an application window. {\it Note} that this is an extended +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} 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 +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} -\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}}} -\membersection{wxDialog::wxDialog}\label{wxdialogconstr} +\membersection{wxDialog::wxDialog}\label{wxdialogctor} \func{}{wxDialog}{\void} @@ -91,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 -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 -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}.} @@ -106,7 +135,7 @@ individual dialog boxes.} \helpref{wxDialog::Create}{wxdialogcreate} -\membersection{wxDialog::\destruct{wxDialog}} +\membersection{wxDialog::\destruct{wxDialog}}\label{wxdialogdtor} \func{}{\destruct{wxDialog}}{\void} @@ -131,9 +160,29 @@ Centres the dialog box on the display. \param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp \param{const wxString\& }{name = ``dialogBox"}} -Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogconstr}\rtfsp +Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogctor}\rtfsp for details. +\membersection{wxDialog::CreateButtonSizer}\label{wxdialogcreatebuttonsizer} + +\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. + +The sizer lays out the buttons in a manner appropriate to the platform. + +This function simply calls \helpref{CreateStdDialogButtonSizer}{wxdialogcreatestddialogbuttonsizer}. + +\membersection{wxDialog::CreateStdDialogButtonSizer}\label{wxdialogcreatestddialogbuttonsizer} + +\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. + +The sizer lays out the buttons in a manner appropriate to the platform. + \membersection{wxDialog::EndModal}\label{wxdialogendmodal} \func{void}{EndModal}{\param{int }{retCode}} @@ -181,45 +230,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. - -\membersection{wxDialog::OnCharHook}\label{wxdialogoncharhook} - -\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}} - -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} - -\wxheading{Remarks} - -wxDialog implements this handler to fake a cancel command if the escape key has been -pressed. This will dismiss the dialog. +Returns true if the dialog box is modal, false otherwise. \membersection{wxDialog::OnApply}\label{wxdialogonapply} @@ -244,7 +279,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 +295,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 +360,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 +400,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}