Added wxRect::Intersect() documentation (patch 1868322 from Laurent Humbertclaude).

[wxWidgets.git] / docs / latex / wx / tdialog.tex

\section{wxDialog overview}\label{wxdialogoverview}

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:

\begin{enumerate}
\item A surrounding frame is implicitly created.
\item Extra functionality is automatically given to the dialog box,
  such as tabbing between items (currently Windows only).
\item If the dialog box is {\it modal}, the calling program is blocked
  until the dialog box is dismissed.
\end{enumerate}

For a set of dialog convenience functions, including file selection, see
\rtfsp\helpref{Dialog functions}{dialogfunctions}.

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.