\Header{grid.layout}{Create a Grid Layout}
\keyword{dplot}{grid.layout}
\begin{Description}\relax
This function returns a Grid layout, which describes a subdivision
of a rectangular region.\end{Description}
\begin{Usage}
\begin{verbatim}
grid.layout(nrow = 1, ncol = 1,
        widths = unit(rep(1, ncol), "null"),
        heights = unit(rep(1, nrow), "null"),
        default.units = "null", respect = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{nrow}] An integer describing the number of rows in the layout.
\item[\code{ncol}] An integer describing the number of columns in the layout.
\item[\code{widths}] A numeric vector or unit object
describing the widths of the columns
in the layout.
\item[\code{heights}] A numeric vector or unit object
describing the heights of the rows
in the layout.
\item[\code{default.units}] A string indicating the default units to use
if \code{widths} or \code{heights} are only given as numeric vectors.
\item[\code{respect}] A logical value indicating whether
row heights and column widths should respect each other.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The unit objects given for the \code{widths} and \code{heights}
of a layout may use a special \code{units} that only has
meaning for layouts.  This is the \code{"null"} unit, which
indicates what relative fraction of the available width/height the
column/row occupies.  See the reference for a better description
of relative widths and heights in layouts.\end{Details}
\begin{Value}
A Grid layout object.\end{Value}
\begin{Section}{WARNING}
This function must NOT be confused with the base R graphics function
\code{layout}.  In particular, do not use \code{layout} in
combination with Grid graphics.  The documentation for
\code{layout} may provide some useful information and this
function should behave identically in comparable situations.  The
\code{grid.layout} 
function has \emph{added} the ability to specify a broader range
of units for row heights and column widths, and allows for nested
layouts (see \code{viewport}).\end{Section}
\begin{Author}\relax
Paul Murrell\end{Author}
\begin{References}\relax
Murrell, P. R. (1999), Layouts: A Mechanism for Arranging
Plots on a Page, \emph{Journal of Computational and Graphical
Statistics}, \bold{8}, 121--134.\end{References}
\begin{SeeAlso}\relax
\link{Grid},
\code{\Link{grid.show.layout}},
\code{\Link{viewport}},
\code{\Link{layout}}\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## A variety of layouts (some a bit mid-bending ...)
layout.torture()
\end{ExampleCode}
\end{Examples}

