X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c6ad433beab62c3108b61bbc2b682302607f6bf..83930b2fd2c41cd965926e669115696c1e8eef0d:/docs/latex/wx/dialog.tex diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex index e75229c42e..9181cc2060 100644 --- a/docs/latex/wx/dialog.tex +++ b/docs/latex/wx/dialog.tex @@ -1,3 +1,14 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: dialog.tex +%% Purpose: wxDialog documentation +%% Author: wxWidgets Team +%% Modified by: +%% Created: +%% RCS-ID: $Id$ +%% Copyright: (c) wxWidgets Team +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \section{\class{wxDialog}}\label{wxdialog} A dialog box is a window with a title bar and sometimes a system menu, which @@ -6,6 +17,7 @@ is usually used to allow the user to make some choice or to answer a question. \wxheading{Derived from} +\helpref{wxTopLevelWindow}{wxtoplevelwindow}\\ \helpref{wxWindow}{wxwindow}\\ \helpref{wxEvtHandler}{wxevthandler}\\ \helpref{wxObject}{wxobject} @@ -19,14 +31,15 @@ is usually used to allow the user to make some choice or to answer a question. 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 +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 dialogs are one of the very few examples of +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 +In other words, although this code snippet: + \begin{verbatim} void AskUser() { @@ -38,8 +51,10 @@ In other words, although this code snippet dlg->Destroy(); } \end{verbatim} + works, you can also achieve the same result by using a simpler code fragment below: + \begin{verbatim} void AskUser() { @@ -51,13 +66,7 @@ below: } \end{verbatim} -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 +An application can define a \helpref{wxCloseEvent}{wxcloseevent} handler for the dialog to respond to system close events. \wxheading{Window styles} @@ -65,23 +74,25 @@ the dialog to respond to system close events. \twocolwidtha{5cm} \begin{twocollist}\itemsep=0pt \twocolitem{\windowstyle{wxCAPTION}}{Puts a caption on the dialog box.} -\twocolitem{\windowstyle{wxDEFAULT\_DIALOG\_STYLE}}{Equivalent to a combination of wxCAPTION, wxCLOSE and wxSYSTEM\_MENU (the last one is not used under Unix)} +\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}}{Displays a close box on the frame.} +\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{wxSTAY\_ON\_TOP}}{The dialog stays on top of all other windows.} \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\_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 +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).} +\twocolitem{\windowstyle{wxDIALOG\_EX\_METAL}}{On Mac OS X, frames with this style will be shown with a metallic look. This is an {\it extra} style.} \end{twocollist} Under Unix or Linux, MWM (the Motif Window Manager) or other window managers @@ -92,12 +103,13 @@ 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} @@ -121,10 +133,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}.} @@ -136,12 +148,14 @@ individual dialog boxes.} \helpref{wxDialog::Create}{wxdialogcreate} -\membersection{wxDialog::\destruct{wxDialog}} + +\membersection{wxDialog::\destruct{wxDialog}}\label{wxdialogdtor} \func{}{\destruct{wxDialog}}{\void} Destructor. Deletes any child windows before deleting the physical window. + \membersection{wxDialog::Centre}\label{wxdialogcentre} \func{void}{Centre}{\param{int}{ direction = wxBOTH}} @@ -152,6 +166,7 @@ Centres the dialog box on the display. \docparam{direction}{May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL} or {\tt wxBOTH}.} + \membersection{wxDialog::Create}\label{wxdialogcreate} \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp @@ -161,9 +176,42 @@ 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::DoOK}\label{wxdialogdook} + +\func{virtual bool}{DoOK}{\void} + +This function is called when the titlebar OK button is pressed (PocketPC only). +A command event for the identifier returned by GetAffirmativeId is sent by +default. You can override this function. If the function returns false, wxWidgets +will call Close() for the dialog. + + \membersection{wxDialog::EndModal}\label{wxdialogendmodal} \func{void}{EndModal}{\param{int }{retCode}} @@ -181,6 +229,30 @@ invocation. \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode} + +\membersection{wxDialog::GetAffirmativeId}\label{wxdialoggetaffirmativeid} + +\constfunc{int}{GetAffirmativeId}{\void} + +Gets the identifier to be used when the user presses an OK button in a PocketPC titlebar. + +\wxheading{See also} + +\helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid} + + +\membersection{wxDialog::GetEscapeId}\label{wxdialoggetescapeid} + +\constfunc{int}{GetEscapeId}{\void} + +Gets the identifier of the button to map presses of \texttt{\textsc{ESC}} +button to. + +\wxheading{See also} + +\helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid} + + \membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode} \func{int}{GetReturnCode}{\void} @@ -197,11 +269,17 @@ a code to the application. \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp \helpref{wxDialog::EndModal}{wxdialogendmodal} -\membersection{wxDialog::GetTitle}\label{wxdialoggettitle} -\constfunc{wxString}{GetTitle}{\void} +\membersection{wxDialog::GetToolBar}\label{wxdialoggettoolbar} + +\constfunc{wxToolBar*}{GetToolBar}{\void} + +On PocketPC, a dialog is automatically provided with an empty toolbar. GetToolBar +allows you to access the toolbar and add tools to it. Removing tools and adding +arbitrary controls are not currently supported. + +This function is not available on any other platform. -Returns the title of the dialog box. \membersection{wxDialog::Iconize}\label{wxdialogiconized} @@ -221,6 +299,7 @@ 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)}. + \membersection{wxDialog::IsIconized}\label{wxdialogisiconized} \constfunc{bool}{IsIconized}{\void} @@ -231,25 +310,13 @@ Returns true if the dialog box is iconized. Windows only. 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. \membersection{wxDialog::OnApply}\label{wxdialogonapply} @@ -259,12 +326,13 @@ The default handler for the wxID\_APPLY identifier. \wxheading{Remarks} -This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}. +This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}. \wxheading{See also} \helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel} + \membersection{wxDialog::OnCancel}\label{wxdialogoncancel} \func{void}{OnCancel}{\param{wxCommandEvent\& }{event}} @@ -280,6 +348,7 @@ sets the return value to wxID\_CANCEL and calls {\bf Show(false)} if the dialog \helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnApply}{wxdialogonapply} + \membersection{wxDialog::OnOK}\label{wxdialogonok} \func{void}{OnOK}{\param{wxCommandEvent\& }{event}} @@ -297,6 +366,7 @@ sets the return value to wxID\_OK and calls {\bf Show(false)} if the dialog is m \helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply} + \membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged} \func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}} @@ -319,6 +389,32 @@ propagate the notification to child windows and controls. \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent} + +\membersection{wxDialog::SetAffirmativeId}\label{wxdialogsetaffirmativeid} + +\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. + +\wxheading{See also} + +\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid} + + +\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 +is interpreted as the id of the button to map the escape key to. + + \membersection{wxDialog::SetIcon}\label{wxdialogseticon} \func{void}{SetIcon}{\param{const wxIcon\& }{icon}} @@ -331,6 +427,7 @@ Sets the icon for this dialog. See also \helpref{wxIcon}{wxicon}. + \membersection{wxDialog::SetIcons}\label{wxdialogseticons} \func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}} @@ -343,11 +440,12 @@ Sets the icons for this dialog. See also \helpref{wxIconBundle}{wxiconbundle}. + \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 +{\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 @@ -357,6 +455,7 @@ until the dialog is hidden) or modeless (control returns immediately). \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}} @@ -377,15 +476,6 @@ a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogend \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}} - -Sets the title of the dialog box. - -\wxheading{Parameters} - -\docparam{title}{The dialog box title.} \membersection{wxDialog::Show}\label{wxdialogshow} @@ -403,6 +493,7 @@ modal, control is returned to the calling program.} The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}. + \membersection{wxDialog::ShowModal}\label{wxdialogshowmodal} \func{int}{ShowModal}{\void} @@ -419,4 +510,3 @@ 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} -