\HeaderA{recordGraphics}{Record graphics operations}{recordGraphics}
\keyword{device}{recordGraphics}
\begin{Description}\relax
Records arbitrary code on the graphics engine display list.
Useful for encapsulating calculations with graphical output
that depends on the calculations.
Intended \emph{only} for expert use.
\end{Description}
\begin{Usage}
\begin{verbatim}
recordGraphics(expr, list, env)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{expr}] object of mode \code{\LinkA{expression}{expression}} or \code{call} or
an unevaluated expression.
\item[\code{list}] a list defining the environment in which \code{expr} is to
be evaluated.
\item[\code{env}] An \code{\LinkA{environment}{environment}} specifying
where \R{} looks for objects not found in
\code{envir}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The code in \code{expr} is evaluated in an environment constructed
from \code{list}, with \code{env} as the parent of that environment.

All three arguments are saved on the graphics engine display list
so that on a device resize or copying between devices, the original
evaluation environment can be recreated and the code can be
re-evaluated to reproduce the graphical output.
\end{Details}
\begin{Value}
The value from evaluating \code{expr}.
\end{Value}
\begin{Section}{Warning}
This function is not intended for general use.  Incorrect or
improper use of this function could lead to unintended and/or
undesirable results.

An example of acceptable use is querying the current state
of a graphics device or graphics system setting and then
calling a graphics function.

An example of improper use would be calling the \code{assign} function
to performing assignments in the global environment.
\end{Section}
\begin{SeeAlso}\relax
\code{\LinkA{eval}{eval}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(graphics)

plot(1:10)
# This rectangle remains 1inch wide when the device is resized
recordGraphics(
  {
    rect(4, 2,
         4 + diff(par("usr")[1:2])/par("pin")[1], 3)
  },
  list(),
  getNamespace("graphics"))
\end{ExampleCode}
\end{Examples}

