run.simplepanel.Rd
\name{run.simplepanel}
\alias{clear.simplepanel}
\alias{redraw.simplepanel}
\alias{run.simplepanel}
\title{
Run Point-and-Click Interface
}
\description{
Execute various operations in a simple
point-and-click user interface.
}
\usage{
run.simplepanel(P, popup=TRUE, verbose = FALSE)
clear.simplepanel(P)
redraw.simplepanel(P, verbose = FALSE)
}
\arguments{
\item{P}{
An interaction panel (object of class \code{"simplepanel"},
created by \code{\link{simplepanel}} or \code{\link{grow.simplepanel}}).
}
\item{popup}{
Logical. If \code{popup=TRUE} (the default),
the panel will be displayed in a
new popup window. If \code{popup=FALSE},
the panel will be displayed on the current graphics
window if it already exists, and on a new window otherwise.
}
\item{verbose}{
Logical. If \code{TRUE}, debugging information will be printed.
}
}
\details{
These commands enable the user to run a simple, robust,
point-and-click interface to any \R code.
The interface is implemented
using only the basic graphics package in \R.
The argument \code{P} is an object of class \code{"simplepanel"},
created by \code{\link{simplepanel}} or \code{\link{grow.simplepanel}},
which specifies the graphics to be displayed and the actions to be performed
when the user interacts with the panel.
The command \code{run.simplepanel(P)} activates the panel:
the display is initialised and the graphics system waits for the
user to click the panel.
While the panel is active, the user can only interact with the panel;
the \R command line interface and the \R GUI cannot be used.
When the panel terminates (typically because the user
clicked a button labelled Exit), control returns to the \R command line
interface and the \R GUI.
The command \code{clear.simplepanel(P)} clears all the display
elements in the panel, resulting in a blank display except for the
title of the panel.
The command \code{redraw.simplepanel(P)} redraws all the buttons
of the panel, according to the \code{redraw} functions contained
in the panel.
If \code{popup=TRUE} (the default), \code{run.simplepanel} begins by
calling \code{\link[grDevices]{dev.new}} so that a new popup window
is created; this window is closed using
\code{\link[grDevices]{dev.off}} when \code{run.simplepanel} terminates.
If \code{popup=FALSE}, the panel will be displayed on the current graphics
window if it already exists, and on a new window otherwise;
this window is not closed when \code{run.simplepanel} terminates.
For more sophisticated control of the graphics focus (for example, to
use the panel to control the display on another window),
initialise the graphics devices yourself using
\code{\link[grDevices]{dev.new}} or similar commands; save these devices
in the shared environment \code{env} of the panel \code{P};
and write the click/redraw functions of \code{P} in such a way that
they access these devices using \code{\link[grDevices]{dev.set}}.
Then use \code{run.simplepanel} with \code{popup=FALSE}.
}
\value{
The return value of \code{run.simplepanel(P)} is the value returned
by the \code{exit} function of \code{P}. See \code{\link{simplepanel}}.
The functions \code{clear.simplepanel} and \code{redraw.simplepanel}
return \code{NULL}.
}
\author{\adrian
and \rolf
}
\seealso{
\code{\link{simplepanel}}
}
\examples{
if(interactive()) {
# make boxes (alternatively use layout.boxes())
Bminus <- square(1)
Bvalue <- shift(Bminus, c(1.2, 0))
Bplus <- shift(Bvalue, c(1.2, 0))
Bdone <- shift(Bplus, c(1.2, 0))
myboxes <- list(Bminus, Bvalue, Bplus, Bdone)
myB <- do.call(boundingbox,myboxes)
# make environment containing an integer count
myenv <- new.env()
assign("answer", 0, envir=myenv)
# what to do when finished: return the count.
myexit <- function(e) { return(get("answer", envir=e)) }
# button clicks
# decrement the count
Cminus <- function(e, xy) {
ans <- get("answer", envir=e)
assign("answer", ans - 1, envir=e)
return(TRUE)
}
# display the count (clicking does nothing)
Cvalue <- function(...) { TRUE }
# increment the count
Cplus <- function(e, xy) {
ans <- get("answer", envir=e)
assign("answer", ans + 1, envir=e)
return(TRUE)
}
# quit button
Cdone <- function(e, xy) { return(FALSE) }
myclicks <- list("-"=Cminus,
value=Cvalue,
"+"=Cplus,
done=Cdone)
# redraw the button that displays the current value of the count
Rvalue <- function(button, nam, e) {
plot(button, add=TRUE)
ans <- get("answer", envir=e)
text(centroid.owin(button), labels=ans)
return(TRUE)
}
# make the panel
P <- simplepanel("Counter",
B=myB, boxes=myboxes,
clicks=myclicks,
redraws = list(NULL, Rvalue, NULL, NULL),
exit=myexit, env=myenv)
P
run.simplepanel(P)
}
}
\keyword{iplot}
\keyword{utilities}