playwith (version 0.9-54)

playDo: Do something in a specified plot space

Description

Part of the playwith Application Programming Interface.

Usage

playDo(playState, expr, space = "plot", clip.off = !isTRUE(playState$clip.annotations), return.code = FALSE)

Arguments

playState

a playState object representing the plot, window and device.

expr

an expression, typically a drawing operation, to evaluate in the plot space. It will be quoted (see examples).

space

the plot space (viewport) to go to before evaluating expr. This can be "plot", "page", or for lattice plots "packet N" (where N is a packet number), or for grid plots the name of a viewport passed to the viewport argument of playwith.

clip.off

enforce no clipping of drawing operations: see clip argument to viewport.

return.code

if TRUE, return code (as an expression) for the given actions, rather than executing them.

Value

the value returned by expr.

Details

This function allows an arbitrary expression to be evaluated while some part of the plot has been made active (i.e. moving to a grid graphics viewport). Grid viewports are used also to represent spaces in a base graphics plot (using the gridBase package. That means expr can always use Grid drawing operations.

The default space="plot" will work for base graphics, grid graphics and for single-panel lattice plots. It will also work for multi-panel lattice plots when one panel is in focus (see trellis.focus).

Using space="page" will apply to the whole device space in normalised device coordinates (0--1).

Other functions such as playSelectData and playPointInput return values that can be used directly for the space argument.

See Also

playwith.API, playSelectData, playPointInput

Examples

if (interactive()) {

library(lattice)
library(grid)

packs <- paste("packet", rep(1:4, each=4))
playwith(xyplot(1:16 ~ 1:16 | packs))
myGp <- gpar(fill="red", col="black", alpha=0.5)

## draw in a specific packet
playDo(playDevCur(), grid.circle(gp=myGp), space="packet 2")

## draw in default space="plot" after focussing on one panel
trellis.focus("panel", 1, 1)
packet.number()  # 1, same as space="packet 1"
playDo(playDevCur(), grid.circle(gp=myGp))
trellis.unfocus()

## space="plot" does not work in a multi-panel plot
## unless one panel is in focus
try(playDo(playDevCur(), grid.circle(gp=myGp)))

## draw on the whole page
playDo(playDevCur(), grid.circle(gp=myGp), space="page")

}