Box.tex

\section{Boxes}

The \fw{Box} module provides two box layout widgets which can be
created the following functions:

\begin{itemize}
\item \fw{vBox} -- creates a box of type \fw{Widget (Box a b)} which
  lays out two children of types \fw{Widget a} and \fw{Widget b}
  vertically
\item \fw{hBox} -- creates a box of type \fw{Widget (Box a b)} which
  lays out two children of types \fw{Widget a} and \fw{Widget b}
  horizontally
\end{itemize}

In addition, the box combinators \fw{<-->} and \fw{<++>} can be used
to create vertical and horizontal boxes, respectively, using widgets
in \fw{IO}.

Box widgets have a \textit{child size policy} which determines how
space in the box is allocated to the child widgets.  The size policy
type is \fw{ChildSizePolicy} and defaults to \fw{PerChild BoxAuto
  BoxAuto} for new boxes.  Each widget can have an individual policy
whose type is \fw{IndividualPolicy}; this policy can be set to
\fw{BoxAuto} or \fw{BoxFixed Int}.  In the former case, space will be
allocated as needed; in the latter, the specified fixed number of rows
or columns (depending on the orientation of the \fw{Box}) will be
used.

Use the \fw{setBoxChildSizePolicy} to change the box size policy to
one of the following kinds of values:

\begin{itemize}
\item \fw{PerChild IndividualPolicy IndividualPolicy} -- set the
  policies for each child widget.
\item \fw{Percentage Int} -- the total available space will be
  allocated as a percentage.  The number specified here is the
  percentage $n$ ($0 \le n \le 100$) allocated to the first child; the
  rest will be allocated to the second.  The \fw{BoxError} exception
  will be raised if an invalid percentage value is specified.
\end{itemize}

Boxes may also be configured with a number of rows or columns of
spacing in between their child widgets; this is accomplished with the
\fw{setBoxSpacing} function.  It takes a number of rows or columns,
depending on the orientation of the box.  The function
\fw{withBoxSpacing} is provided as a convenience for setting the box
spacing in a monadic construction.

The following example creates a box of each type to lay out some text
widgets:

\begin{haskellcode}
 b1 <- (plainText "foo") <++> (plainText "bar") >>= withBoxSpacing 1
 b2 <- (return b1) <--> (plainText "baz") >>= withBoxSpacing 1
\end{haskellcode}

The result is an inner horizontal box, \fw{b1}, containing two
\fw{FormattedText} widgets separated by one column, laid out on top of
another \fw{FormattedText} widget and separated by one row.

\subsubsection{Growth Policy}

\fw{Box}es grow in their respective dimensions if and only if:

\begin{itemize}
\item One or more children can also grow in that dimension, and
\item The children which can grow are in box cells with the
  \fw{Percentage} or \fw{BoxAuto} size policies set.
\end{itemize}

\fw{Box}es grow in other dimensions merely if any children grow in
that dimension.

Consider these examples:

\begin{itemize}
\item A vertical \fw{Box} with a default size policy of \fw{BoxAuto} /
  \fw{BoxAuto} will grow both vertically and horizontally if either
  child grows respectively.
\item A vertical \fw{Box} with fixed-size cells will never grow
  vertically, but will grow horizontally if either child does.
\item A horizontal \fw{Box} with one fixed-size cell will grow
  horizontally if the child in the flexible cell grows horizontally.
\end{itemize}