\section{wxDialog overview}\label{wxdialogoverview}
-Classes: \helpref{wxDialog}{wxdialog}
+Classes: \helpref{wxDialog}{wxdialog}, \helpref{wxDialogLayoutAdapter}{wxdialoglayoutadapter}
A dialog box is similar to a panel, in that it is a window which can
be used for placing controls, with the following exceptions:
until the dialog box is dismissed.
\end{enumerate}
-Under Windows 3, modal dialogs have to be emulated using
-modeless dialogs and a message loop. This is because Windows 3 expects
-the contents of a modal dialog to be loaded from a resource file or
-created on receipt of a dialog initialization message. This is too
-restrictive for wxWidgets, where any window may be created and displayed
-before its contents are created.
-
For a set of dialog convenience functions, including file selection, see
\rtfsp\helpref{Dialog functions}{dialogfunctions}.
-See also \helpref{wxPanel}{wxpanel} and \helpref{wxWindow}{wxwindow} for inherited
-member functions. Validation of data in controls is covered
-in \helpref{Validator overview}{validatoroverview}.
+See also \helpref{wxTopLevelWindow}{wxtoplevelwindow} and \helpref{wxWindow}{wxwindow} for inherited
+member functions. Validation of data in controls is covered in \helpref{Validator overview}{validatoroverview}.
+
+\subsection{Automatic scrolling dialogs}\label{autoscrollingdialogs}
+
+As an ever greater variety of mobile hardware comes to market, it becomes more imperative for wxWidgets applications to adapt
+to these platforms without putting too much burden on the programmer. One area where wxWidgets can help is in adapting
+dialogs for the lower resolution screens that inevitably accompany a smaller form factor. wxDialog therefore supplies
+a global \helpref{wxDialogLayoutAdapter}{wxdialoglayoutadapter} class that implements automatic scrolling adaptation for most sizer-based custom dialogs.
+Many applications should therefore be able to adapt to small displays with little or no work, as far as dialogs are concerned.
+
+By default this adaptation is off. To switch scrolling adaptation on globally in your application, call the static function\rtfsp
+\helpref{wxDialog::EnableLayoutAdaptation}{wxdialogenablelayoutadaptation} passing \true. You can also adjust adaptation on a per-dialog basis by calling\rtfsp
+\helpref{wxDialog::SetLayoutAdaptationMode}{wxdialogsetlayoutadaptationmode} with one of {\tt wxDIALOG\_ADAPTATION\_MODE\_DEFAULT} (use the global setting), {\tt wxDIALOG\_ADAPTATION\_MODE\_ENABLED} or {\tt wxDIALOG\_ADAPTATION\_MODE\_DISABLED}.
+The last two modes override the global adaptation setting.
+
+With adaptation enabled, if the display size is too small for the dialog, wxWidgets (or rather the
+standard adapter class wxStandardDialogLayoutAdapter) will
+make part of the dialog scrolling, leaving standard buttons in a non-scrolling part at the bottom of the dialog.
+
+This is done as follows, in \helpref{wxDialogLayoutAdapter::DoLayoutAdaptation}{wxdialoglayoutadapterdolayoutadaptation} called from within wxDialog::Show or wxDialog::ShowModal:
+
+\begin{enumerate}
+\item If \helpref{wxDialog::GetContentWindow}{wxdialoggetcontentwindow} returns a window derived from wxBookCtrlBase, the pages are made scrollable and
+no other adaptation is done.
+\item wxWidgets looks for a \helpref{wxStdDialogButtonSizer}{wxstddialogbuttonsizer} and uses it for the non-scrolling part.
+\item If that search failed, wxWidgets looks for a horizontal \helpref{wxBoxSizer}{wxboxsizer} with one or more
+standard buttons, with identifiers such as {\tt wxID\_OK} and {\tt wxID\_CANCEL}.
+\item If that search failed too, wxWidgets finds 'loose' standard buttons (in any kind of sizer) and adds them to a \helpref{wxStdDialogButtonSizer}{wxstddialogbuttonsizer}.
+If no standard buttons were found, the whole dialog content will scroll.
+\item All the children apart from standard buttons are reparented onto a new \helpref{wxScrolledWindow}{wxscrolledwindow} object,
+using the old top-level sizer for the scrolled window and creating a new top-level sizer to lay out the scrolled window and
+standard button sizer.
+\end{enumerate}
+
+\wxheading{Customising scrolling adaptation}
+
+In addition to switching adaptation on and off globally and per dialog, you can choose how aggressively wxWidgets will
+search for standard buttons by setting \helpref{wxDialog::SetLayoutAdaptationLevel}{wxdialogsetlayoutadaptationlevel}. By default,
+all the steps described above will be performed but by setting the level to 1, for example, you can choose to only look for wxStdDialogButtonSizer.
+
+You can use \helpref{wxDialog::AddMainButtonId}{wxdialogaddmainbuttonid} to add identifiers for buttons that should also be
+treated as standard buttons for the non-scrolling area.
+
+You can derive your own class from \helpref{wxDialogLayoutAdapter}{wxdialoglayoutadapter} or wxStandardDialogLayoutAdapter and call\rtfsp
+\helpref{wxDialog::SetLayoutAdapter}{wxdialogsetlayoutadapter}, deleting the old object that this function returns. Override
+the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability and perform the adaptation.
+
+You can also override \helpref{wxDialog::CanDoLayoutAdaptation}{wxdialogcandolayoutadaptation} and \helpref{wxDialog::DoLayoutAdaptation}{wxdialogdolayoutadaptation} in a class derived from wxDialog.
+
+\wxheading{Situations where automatic scrolling adaptation may fail}
+
+Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof, and may fail in the following situations.
+
+\begin{itemize}
+\item The dialog doesn't use sizers.
+\item The dialog implementation makes assumptions about the window hierarchy, for example getting the parent of a control and casting to the dialog class.
+\item The dialog does custom painting and/or event handling not handled by the scrolled window. If this problem can be solved globally,
+you can derive a new adapter class from wxStandardDialogLayoutAdapter and override its CreateScrolledWindow function to return an instance of your own class.
+\item The dialog has unusual layout, for example a vertical sizer containing a mixture of standard buttons and other controls.
+\item The dialog makes assumptions about the sizer hierarchy, for example to show or hide children of the top-level sizer. However, the original sizer hierarchy will still hold
+until Show or ShowModal is called.
+\end{itemize}
+
+You can help make sure that your dialogs will continue to function after adaptation by:
+
+\begin{itemize}
+\item avoiding the above situations and assumptions;
+\item using \helpref{wxStdDialogButtonSizer}{wxstddialogbuttonsizer};
+\item only making assumptions about hierarchy immediately after the dialog is created;
+\item using an intermediate sizer under the main sizer, a false top-level sizer that can be relied on to exist
+for the purposes of manipulating child sizers and windows;
+\item overriding \helpref{wxDialog::GetContentWindow}{wxdialoggetcontentwindow} to return a book control if your dialog implements pages: wxWidgets will then only make the pages
+scrollable.
+\end{itemize}
+
+\wxheading{wxPropertySheetDialog and wxWizard}
+Adaptation for wxPropertySheetDialog is always done by simply making the pages scrollable, since \helpref{wxDialog::GetContentWindow}{wxdialoggetcontentwindow} returns
+the dialog's book control and this is handled by the standard layout adapter.
+wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions rather than the global adapter: again, only the wizard pages are made scrollable.
projects / wxWidgets.git / blobdiff