X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/60fef9643dfbe219c51db7218d9cfa846b258f2c..c266eff98c5e44012647f54f38a1e29ecabd8759:/docs/latex/wx/dialog.tex?ds=sidebyside diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex index 1ab082deeb..31818d2c9b 100644 --- a/docs/latex/wx/dialog.tex +++ b/docs/latex/wx/dialog.tex @@ -13,7 +13,25 @@ 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. +is often used to allow the user to make some choice or to answer a question. + + +\wxheading{Dialog Buttons} + +The dialog usually contains either a single button allowing to close the +dialog or two buttons, one accepting the changes and the other one discarding +them (such button, if present, is automatically activated if the user presses +the \texttt{"Esc"} key). By default, buttons with the standard \texttt{wxID\_OK} +and \texttt{wxID\_CANCEL} identifiers behave as expected. Starting with +wxWidgets 2.7 it is also possible to use a button with a different identifier +instead, see \helpref{SetAffirmativeId}{wxdialogsetaffirmativeid} and +\helpref{SetEscapeId}{wxdialogsetescapeid}. + +Also notice that the \helpref{CreateButtonSizer()}{wxdialogcreatebuttonsizer} +should be used to create the buttons appropriate for the current platform and +positioned correctly (including their order which is platform-dependent). + + \wxheading{Derived from} @@ -26,7 +44,11 @@ is usually used to allow the user to make some choice or to answer a question. -\wxheading{Remarks} +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + +\wxheading{Modal and modeless dialogs} 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, @@ -185,11 +207,28 @@ for details. \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. +of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, +wxHELP, wxNO\_DEFAULT. The sizer lays out the buttons in a manner appropriate to the platform. -This function simply calls \helpref{CreateStdDialogButtonSizer}{wxdialogcreatestddialogbuttonsizer}. +This function uses \helpref{CreateStdDialogButtonSizer}{wxdialogcreatestddialogbuttonsizer} +internally for most platforms but doesn't create the sizer at all for the +platforms with hardware buttons (such as smartphones) for which it sets up the +hardware buttons appropriately and returns \NULL, so don't forget to test that +the return value is valid before using it. + + +\membersection{wxDialog::CreateSeparatedButtonSizer}\label{wxdialogcreateseparatedbuttonsizer} + +\func{wxSizer*}{CreateSeparatedButtonSizer}{\param{long}{ flags}} + +Creates a sizer with standard buttons using +\helpref{CreateButtonSizer}{wxdialogcreatebuttonsizer} separated from the rest +of the dialog contents by a horizontal \helpref{wxStaticLine}{wxstaticline}. + +Please notice that just like CreateButtonSizer() this function may return \NULL +if no buttons were created. \membersection{wxDialog::CreateStdDialogButtonSizer}\label{wxdialogcreatestddialogbuttonsizer} @@ -197,7 +236,8 @@ This function simply calls \helpref{CreateStdDialogButtonSizer}{wxdialogcreatest \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. +of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, +wxHELP, wxNO\_DEFAULT. The sizer lays out the buttons in a manner appropriate to the platform. @@ -234,7 +274,8 @@ invocation. \constfunc{int}{GetAffirmativeId}{\void} -Gets the identifier to be used when the user presses an OK button in a PocketPC titlebar. +Gets the identifier of the button which works like standard OK button in this +dialog. \wxheading{See also} @@ -283,7 +324,7 @@ This function is not available on any other platform. \membersection{wxDialog::Iconize}\label{wxdialogiconized} -\func{void}{Iconize}{\param{const bool}{ iconize}} +\func{void}{Iconize}{\param{bool}{ iconize}} Iconizes or restores the dialog. Windows only. @@ -318,54 +359,6 @@ Always returns false under Windows since dialogs cannot be iconized. Returns true if the dialog box is modal, false otherwise. -\membersection{wxDialog::OnApply}\label{wxdialogonapply} - -\func{void}{OnApply}{\param{wxCommandEvent\& }{event}} - -The default handler for the wxID\_APPLY identifier. - -\wxheading{Remarks} - -This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}. - -\wxheading{See also} - -\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel} - - -\membersection{wxDialog::OnCancel}\label{wxdialogoncancel} - -\func{void}{OnCancel}{\param{wxCommandEvent\& }{event}} - -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. - -\wxheading{See also} - -\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnApply}{wxdialogonapply} - - -\membersection{wxDialog::OnOK}\label{wxdialogonok} - -\func{void}{OnOK}{\param{wxCommandEvent\& }{event}} - -The default handler for the wxID\_OK identifier. - -\wxheading{Remarks} - -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. - -\wxheading{See also} - -\helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply} - \membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged} @@ -394,24 +387,38 @@ propagate the notification to child windows and controls. \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. +Sets the identifier to be used as OK button. When the button with this +identifier is pressed, the dialog calls \helpref{Validate}{wxwindowvalidate} +and \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow} +and, if they both return \true, closes the dialog with \texttt{wxID\_OK} return +code. + +Also, when the user presses a hardware OK button on the devices having one or +the special OK button in the PocketPC title bar, an event with this id is +generated. + +By default, the affirmative id is wxID\_OK. \wxheading{See also} -\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid} +\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid}, \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid} \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 +Sets the identifier of the button which should work like the standard +\texttt{\textsc{Cancel}} button in this dialog. When the button with this id is +clicked, the dialog is closed. Also, when the user presses \texttt{\textsc{ESC}} +key in the dialog or closes the dialog using the close button in the title bar, +this is mapped to the click of the button with the specified id. + +By default, the escape id is the special value \texttt{wxID\_ANY} meaning that +\texttt{wxID\_CANCEL} button is used if it's present in the dialog and +otherwise the button with \helpref{GetAffirmativeId()}{wxdialoggetaffirmativeid} +is used. Another special value for \arg{id} is \texttt{wxID\_NONE} meaning that +\texttt{\textsc{ESC}} presses should be ignored. If any other value is given, it is interpreted as the id of the button to map the escape key to. @@ -443,7 +450,7 @@ See also \helpref{wxIconBundle}{wxiconbundle}. \membersection{wxDialog::SetModal}\label{wxdialogsetmodal} -\func{void}{SetModal}{\param{const bool}{ flag}} +\func{void}{SetModal}{\param{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. @@ -479,7 +486,7 @@ a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogend \membersection{wxDialog::Show}\label{wxdialogshow} -\func{bool}{Show}{\param{const bool}{ show}} +\func{bool}{Show}{\param{bool}{ show}} Hides or shows the dialog. @@ -510,3 +517,4 @@ 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} +