% File src/library/grid/vignettes/interactive.Rnw
% Part of the R package, https://www.R-project.org
% Copyright 2001-13 Paul Murrell and the R Core Team
% Distributed under GPL 2 or later

\documentclass[a4paper]{article}
%\VignetteIndexEntry{Editing grid Graphics}
%\VignettePackage{grid}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\pkg}[1]{{\normalfont\fontseries{b}\selectfont #1}}
\newcommand{\grid}{\pkg{grid}}
\newcommand{\R}{{\sffamily R}}
\setlength{\parindent}{0in}
\setlength{\parskip}{.1in}
\setlength{\textwidth}{140mm}
\setlength{\oddsidemargin}{10mm}
\title{An Example of Interactive Graphics Editing in \grid}
\author{Paul Murrell}

\begin{document}
\maketitle

<<echo=FALSE, results=hide>>=
library(grDevices)
library(grid)
ps.options(pointsize = 12)
options(width = 60)
@
First of all, we create an x-axis and draw it on the device.
It is very important that we specify a \code{name} for the object
so that we can refer to it later.

<<fig1, results=hide, fig=TRUE, width=6, height=2, include=FALSE>>=
grid.xaxis(at = 1:4/5, vp = viewport(w = .5, h = 0.01), name = "gxa")
@
\begin{center}
{
\includegraphics[width=3in, height=1in]{interactive-fig1}
}
\end{center}
@

Now we edit the axis, changing the colour of the entire axis to red.
Notice that we refer to the x-axis by its name.

<<edit1, eval=FALSE>>=
grid.edit("gxa", gp = gpar(col = "red"))
<<fig2, echo=FALSE, results=hide, fig=TRUE, width=6, height=2, include=FALSE>>=
gxa <- xaxisGrob(at = 1:4/5, vp = viewport(w = .5, h = .01))
gxa <- editGrob(gxa, gp = gpar(col = "red"))
grid.draw(gxa)
@
\begin{center}
{
\includegraphics[width=3in, height=1in]{interactive-fig2}
}
\end{center}

@

Now we change just the labels of the x-axis to green.  We use the
\code{gPath()} function to concatenate the grob names (we could have used
\code{"gxa::labels"} here, but \code{gPath()} is recommended for
writing code that will be reused).

<<edit2, eval=FALSE>>=
grid.edit(gPath("gxa", "labels"), gp = gpar(col = "green"))
<<fig3, echo=FALSE, results=hide, fig=TRUE, width=6, height=2, include=FALSE>>=
gxa <- xaxisGrob(at = 1:4/5, vp = viewport(w = .5, h = .01))
gxa <- editGrob(gxa, gp = gpar(col = "red"))
gxa <- editGrob(gxa, gPath = "labels", gp = gpar(col = "green"))
grid.draw(gxa)
@
\begin{center}
{
\includegraphics[width=3in, height=1in]{interactive-fig3}
}
\end{center}
@

It is also possible to change the number of tick marks.
Notice that the labels all change back to red;  this happens
because new labels are created by the axis and these ``inherit''
the colour of the axis by default.  In other words, the
colour specification of the old labels was specific to the old labels
and was discarded when the old labels were discarded.

<<edit3, eval=FALSE>>=
grid.edit("gxa", at = c(0.0, 0.5, 1.0))
<<fig4, echo=FALSE, results=hide, fig=TRUE, width=6, height=2, include=FALSE>>=
gxa <- xaxisGrob(at = 1:4/5, vp = viewport(w = .5, h = .01))
gxa <- editGrob(gxa, gp = gpar(col = "red"))
gxa <- editGrob(gxa, gPath = "labels", gp = gpar(col = "green"))
gxa <- editGrob(gxa, at = c(0.0, 0.5, 1.0))
grid.draw(gxa)
@
\begin{center}
{
\includegraphics[width=3in, height=1in]{interactive-fig4}
}
\end{center}
@

Finally, we change the labels back to black and rotate them all $30\deg$.

<<edit4, eval=FALSE>>=
grid.edit("gxa::labels", gp = gpar(col = "black"), rot = 30)
<<fig5, echo=FALSE, results=hide, fig=TRUE, width=6, height=2, include=FALSE>>=
gxa <- xaxisGrob(at = 1:4/5, vp = viewport(w = .5, h = .01))
gxa <- editGrob(gxa, gp = gpar(col = "red"))
gxa <- editGrob(gxa, gPath = "labels", gp = gpar(col = "green"))
gxa <- editGrob(gxa, at = c(0.0, 0.5, 1.0))
gxa <- editGrob(gxa, gPath = "labels", gp = gpar(col = "black"), rot = 30)
grid.draw(gxa)
@
\begin{center}
{
\includegraphics[width=3in, height=1in]{interactive-fig5}
}
\end{center}
@

The above examples describe how to perform editing on a grid object
and have the changes updated on screen.  The equivalent can be done
entirely ``off-screen'', by just working with the grid object.
The off-screen equivalent in this case would look like:

<<results=hide>>=
gxa <- xaxisGrob(at = 1:4/5, vp = viewport(w = .5, h = .01))
gxa <- editGrob(gxa, gp = gpar(col = "red"))
gxa <- editGrob(gxa, gPath = "labels", gp = gpar(col = "green"))
gxa <- editGrob(gxa, at = c(0.0, 0.5, 1.0))
gxa <- editGrob(gxa, gPath = "labels", gp = gpar(col = "black"), rot = 30)
grid.draw(gxa)
@
\end{document}