Dialog.tex

\section{Dialogs}
\label{sec:dialogs}

The \fw{Dialog} module provides a basic accept/cancel dialog widget
interface and is capable of embedding arbitrary widgets.

Dialog creation is straightforward.  The following example will create
a new dialog with an embedded \fw{Edit} widget and will set the
\fw{Dialog}'s title:

\begin{haskellcode}
 fg1 <- newFocusGroup
 e <- editWidget
 addToFocusGroup fg e

 (dlg, fg2) <- newDialog e "The Title"
 fg <- mergeFocusGroups fg1 fg2
\end{haskellcode}

The \fw{newDialog} function returns a \fw{Dialog} and a
\fw{FocusGroup}.  The \fw{Dialog} includes two \fw{Button}s -- an
``OK'' button and a ``Cancel'' button -- and the returned
\fw{Focus\-Group} contains those buttons in that order.  You can merge
the \fw{FocusGroup} with your own or use it directly as described in
Section \ref{sec:focus}.

The \fw{Dialog} itself is a composite type; the way to lay out a
\fw{Dialog} in your interface is by laying out the \fw{Dialog}'s
widget:

\begin{haskellcode}
 let ui = dialogWidget dlg
\end{haskellcode}

The \fw{Dialog} type provides two events: acceptance and cancellation.
The following example registers handlers for both of these events.
These events are triggered when the user ``presses'' the buttons in
the \fw{Dialog}.

\begin{haskellcode}
 dlg `onDialogAccept` \this ->
   ...
 dlg `onDialogCancel` \this ->
   ...
\end{haskellcode}

To programmatically trigger the acceptance or cancellation of a
\fw{Dialog}, use the \fw{accept\-Dialog} and \fw{cancel\-Dialog}
functions.

\subsubsection{Growth Policy}

A \fw{Dialog}'s growth policy depends on the growth policy of the
widget embedded in it.  The \fw{Dialog}'s interface uses fixed-size
widgets, so it will not grow in either dimension unless you embed a
widget which grows.  In the example above, the \fw{Dialog} will grow
horizontally due to the \fw{Edit} widget but will not grow vertically.