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}
<wx/dialog.h>
-\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,
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}
\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.
\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}
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}
\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}
\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}
\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.
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}
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.
\membersection{wxDialog::Show}\label{wxdialogshow}
-\func{bool}{Show}{\param{const bool}{ show}}
+\func{bool}{Show}{\param{bool}{ show}}
Hides or shows the dialog.
\helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
\helpref{wxDialog:GetReturnCode}{wxdialoggetreturncode},\rtfsp
\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
+
projects / wxWidgets.git / blobdiff