\HeaderA{grid.record}{Encapsulate calculations and drawing}{grid.record}
\aliasA{recordGrob}{grid.record}{recordGrob}
\keyword{dplot}{grid.record}
\begin{Description}\relax
Evaluates an expression that includes both calculatons
and drawing that depends on the calculations so that
both the calculations and the drawing will be rerun when
the scene is redrawn (e.g., device resize or editing).

Intended \emph{only} for expert use.
\end{Description}
\begin{Usage}
\begin{verbatim}
recordGrob(expr, list, name=NULL, gp=NULL, vp=NULL)
grid.record(expr, list, name=NULL, gp=NULL, vp=NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{expr}] object of mode \code{\LinkA{expression}{expression}} or \code{call} or
an \dQuote{unevaluated expression}.
\item[\code{list}] a list defining the environment in which \code{expr} is to
be evaluated.
\item[\code{name}] A character identifier. 
\item[\code{gp}] An object of class \code{gpar}, typically the output
from a call to the function \code{gpar}.  This is basically
a list of graphical parameter settings.
\item[\code{vp}] A Grid viewport object (or NULL).
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
A grob is created of special class \code{"recordedGrob"}
(and drawn, in the case of \code{grid.record}).
The \code{drawDetails} method for this class
evaluates the expression with the list as the evaluation
environment (and the grid Namespace as the parent of that
environment).
\end{Details}
\begin{Note}\relax
This function \emph{must} be used instead of the
function \code{recordGraphics};  all of the dire warnings
about using \code{recordGraphics} responsibly also apply here.
\end{Note}
\begin{Author}\relax
Paul Murrell
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{recordGraphics}{recordGraphics}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
grid.record({
              w <- convertWidth(unit(1, "inches"), "npc")
                      grid.rect(width=w)
            },
            list())
\end{ExampleCode}
\end{Examples}

