X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6500a868fe571da49a36487a1942b12e5393ab4a..302511a3ca8d831ee26c7dfc47c928e8fed8fef6:/docs/latex/wx/dialog.tex diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex index 6e9e17d8b4..f6fa0d8261 100644 --- a/docs/latex/wx/dialog.tex +++ b/docs/latex/wx/dialog.tex @@ -13,7 +13,24 @@ 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. + +Dialogs can be made scrollable, automatically: please see \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for further details. + +\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 +43,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, @@ -155,6 +176,22 @@ individual dialog boxes.} Destructor. Deletes any child windows before deleting the physical window. +\membersection{wxDialog::AddMainButtonId}\label{wxdialogaddmainbuttonid} + +\func{void}{AddMainButtonId}{\param{wxWindowID}{ id}} + +Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + +\membersection{wxDialog::CanDoLayoutAdaptation}\label{wxdialogcandolayoutadaptation} + +\func{bool}{CanDoLayoutAdapation}{\void} + +Returns \true if this dialog can and should perform layout adaptation using \helpref{DoLayoutAdaptation}{wxdialogdolayoutadaptation}, usually if +the dialog is too large to fit on the display. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. \membersection{wxDialog::Centre}\label{wxdialogcentre} @@ -185,7 +222,8 @@ 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. @@ -213,10 +251,18 @@ if no buttons were created. \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. +\membersection{wxDialog::DoLayoutAdaptation}\label{wxdialogdolayoutadaptation} + +\func{bool}{DoLayoutAdapation}{\void} + +Performs layout adaptation, usually if the dialog is too large to fit on the display. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. \membersection{wxDialog::DoOK}\label{wxdialogdook} @@ -227,6 +273,14 @@ 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::EnableLayoutAdaptation}\label{wxdialogenablelayoutadaptation} + +\func{static void}{EnableLayoutAdaptation}{\param{bool}{ enable}} + +A static function enabling or disabling layout adaptation for all dialogs. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + \membersection{wxDialog::EndModal}\label{wxdialogendmodal} @@ -257,6 +311,13 @@ dialog. \helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid} +\membersection{wxDialog::GetContentWindow}\label{wxdialoggetcontentwindow} + +\constfunc{wxWindow*}{GetContentWindow}{\void} + +Override this to return a window containing the main content of the dialog. This is +particularly useful when the dialog implements pages, such as wxPropertySheetDialog, +and allows the \helpref{layout adaptation code}{wxdialogoverview} to know that only the pages need to be made scrollable. \membersection{wxDialog::GetEscapeId}\label{wxdialoggetescapeid} @@ -270,6 +331,50 @@ button to. \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid} +\membersection{wxDialog::GetLayoutAdaptationDone}\label{wxdialoggetlayoutadaptationdone} + +\constfunc{bool}{GetLayoutAdaptationDone}{\void} + +Returns \true if the dialog has been adapted, usually by making it scrollable to work with a small display. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::GetLayoutAdaptationLevel}\label{wxdialoggetlayoutadaptationlevel} + +\func{int}{GetLayoutAdaptationLevel}{\void} + +Gets a value representing the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog. +Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::GetLayoutAdaptationMode}\label{wxdialoggetlayoutadaptationmode} + +\constfunc{wxDialogLayoutAdaptationMode}{GetLayoutAdaptationMode}{\void} + +Gets the adaptation mode, overriding the global adaptation flag. + +See also \helpref{SetLayoutAdaptationMode}{wxdialogsetlayoutadaptationmode} and \helpref{Automatic scrolling dialogs}{autoscrollingdialogs}. + +\membersection{wxDialog::GetLayoutAdapter}\label{wxdialoggetlayoutadapter} + +\func{static wxDialogLayoutAdapter*}{GetLayoutAdapter}{\void} + +A static function getting the current layout adapter object. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::GetMainButtonIds}\label{wxdialoggetmainbuttonids} + +\func{wxArrayInt\&}{GetMainButtonIds}{\void} + +Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + \membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode} \func{int}{GetReturnCode}{\void} @@ -300,7 +405,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. @@ -328,60 +433,30 @@ 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} +\membersection{wxDialog::IsLayoutAdaptationEnabled}\label{wxdialogislayoutadaptationenabled} -\constfunc{bool}{IsModal}{\void} - -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::TransferDataFromWindow}{wxwindowtransferdatafromwindow}. - -\wxheading{See also} - -\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel} +\func{static bool}{IsLayoutAdaptationEnabled}{\void} +A static function returning \true if layout adaptation is enabled for all dialogs. -\membersection{wxDialog::OnCancel}\label{wxdialogoncancel} +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. -\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::IsMainButton}\label{wxdialogismainbutton} +\constfunc{bool}{IsMainButton}{\param{wxWindowID\& }{id}} -\membersection{wxDialog::OnOK}\label{wxdialogonok} +Returns \true if {\it id} is in the array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog. -\func{void}{OnOK}{\param{wxCommandEvent\& }{event}} +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. -The default handler for the wxID\_OK identifier. -\wxheading{Remarks} +\membersection{wxDialog::IsModal}\label{wxdialogismodal} -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. +\constfunc{bool}{IsModal}{\void} -\wxheading{See also} +Returns true if the dialog box is modal, false otherwise. -\helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply} \membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged} @@ -472,9 +547,56 @@ Sets the icons for this dialog. See also \helpref{wxIconBundle}{wxiconbundle}. +\membersection{wxDialog::SetLayoutAdaptationDone}\label{wxdialogsetlayoutadaptationdone} + +\func{void}{SetLayoutAdaptationDone}{\param{bool }{done}} + +Marks the dialog as having been adapted, usually by making it scrollable to work with a small display. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::SetLayoutAdaptationLevel}\label{wxdialogsetlayoutadaptationlevel} + +\func{void}{SetLayoutAdaptationLevel}{\param{int }{level}} + +Sets the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog. +Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::SetLayoutAdaptationMode}\label{wxdialogsetlayoutadaptationmode} + +\func{void}{SetLayoutAdaptationMode}{\param{wxDialogLayoutAdaptationMode }{mode}} + +Sets the adaptation mode, overriding the global adaptation flag. {\it mode} may be one of the following values: + +\begin{verbatim} +enum wxDialogLayoutAdaptationMode +{ + wxDIALOG_ADAPTATION_MODE_DEFAULT = 0, // use global adaptation enabled status + wxDIALOG_ADAPTATION_MODE_ENABLED = 1, // enable this dialog overriding global status + wxDIALOG_ADAPTATION_MODE_DISABLED = 2 // disable this dialog overriding global status +}; +\end{verbatim} + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::SetLayoutAdapter}\label{wxdialogsetlayoutadapter} + +\func{static wxDialogLayoutAdapter*}{SetLayoutAdapter}{\param{wxDialogLayoutAdapter*}{ adapter}} + +A static function for setting the current layout adapter object, returning the old adapter. If you call this, you should +delete the old adapter object. + +See also \helpref{wxDialogLayoutAdapter}{wxdialoglayoutadapter} and \helpref{Automatic scrolling dialogs}{autoscrollingdialogs}. + + \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. @@ -510,7 +632,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. @@ -541,3 +663,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} +