playwith.API {playwith} | R Documentation |
The playwith Application Programming Interface.
playwith
plots (incorporating a plot, window and device)
are represented by a playState
object.
Following is a table of the API functions that can be used to
work with the plot, and to write new interactive tools.
See the links to specific help pages for details.
In case these are insufficient, you may work with the
playState
object itself.
section{Device management}{
These are similar to dev.set
etc.
playDevCur()
playState
– this is not necessarily the active
graphics device.
playDevList()
playState
s.
playDevSet(playState)
playState
, and sets the active
graphics device.
playDevOff(playState)
dev.off()
also
works).
section{Common user commands}{ These functions are also available as menu items.
playGetIDs(playState, type, labels)
playSetIDs(playState, value, type, space,
add, redraw, pos)
type
defaults to "brushed"
;
space
is ignored unless type = "labelled"
.
playClear(playState, type, redraw)
type
s
"annotations"
, "labelled"
, "brushed"
. The
latter will also apply to any linked plots. If
redraw = FALSE
the display will not be updated.
playUndo(playState)
updateLinkedSubscribers(playState, redraw)
playUnlink(playState)
playSourceCode(playState)
section{Interaction}{ These functions allow the user to click or drag on the plot. Click or drag locations are converted into the native coordinates of whatever plot space they occurred in (but are available as device coordinates too).
playSelectData(playState, prompt, scales,
foo)
playPointInput(playState, prompt)
locator
. playLineInput(playState, prompt,
scales)
playRectInput(playState, prompt,
scales)
playPrompt(playState, text)
NULL
to reset. The GUI is
frozen when the prompt is set and unfrozen when reset. playFreezeGUI(playState)
,
playThawGUI(playState)
section{Working with the display}{
playDo(playState, expr, space, clip.off,
return.code)
playAnnotate(playState, annot, space, add, redraw)
rawXLim(playState, space)
rawYLim(playState, space)
rawXLim
, for y axis limits.
spaceCoordsToDataCoords(playState, xy)
dataCoordsToSpaceCoords(playState, xy)
section{Working with the call}{
callArg(playState, arg, eval, data)
mainCall(playState)
playState$call
).
updateMainCall(playState)
main.function
, or by
guessing. This allows callArg()
to work correctly;
it should be called if playState$call
is replaced.
playReplot(playState)
playNewPlot
should be used instead.
playReplot
is triggered when zooming,
editing plot settings, removing annotations, etc.
playNewPlot(playState)
playReplot
.
Note: playNewPlot
is triggered when the call text
is edited manually in the GUI.
section{Working with data}{
xyData(playState, space)
plotCoords
to generate plot locations;
new methods can be defined for non-standard plot types.
xyCoords(playState, space)
xyData
, converted to numeric coordinates.
getDataArg(playState, eval)
data
argument to the plot call, or from a with()
block.
These are similar to dev.set
etc.
playDevCur()
playState
– this is not necessarily the active
graphics device.
playDevList()
playState
s.
playDevSet(playState)
playState
, and sets the active
graphics device.
playDevOff(playState)
dev.off()
also
works).
These functions are also available as menu items.
playGetIDs(playState, type, labels)
playSetIDs(playState, value, type, space,
add, redraw, pos)
type
defaults to "brushed"
;
space
is ignored unless type = "labelled"
.
playClear(playState, type, redraw)
type
s
"annotations"
, "labelled"
, "brushed"
. The
latter will also apply to any linked plots. If
redraw = FALSE
the display will not be updated.
playUndo(playState)
updateLinkedSubscribers(playState, redraw)
playUnlink(playState)
playSourceCode(playState)
These functions allow the user to click or drag on the plot. Click or drag locations are converted into the native coordinates of whatever plot space they occurred in (but are available as device coordinates too).
playSelectData(playState, prompt, scales,
foo)
playPointInput(playState, prompt)
locator
. playLineInput(playState, prompt,
scales)
playRectInput(playState, prompt,
scales)
playPrompt(playState, text)
NULL
to reset. The GUI is
frozen when the prompt is set and unfrozen when reset. playFreezeGUI(playState)
,
playThawGUI(playState)
playDo(playState, expr, space, clip.off,
return.code)
playAnnotate(playState, annot, space, add, redraw)
rawXLim(playState, space)
rawYLim(playState, space)
rawXLim
, for y axis limits.
spaceCoordsToDataCoords(playState, xy)
dataCoordsToSpaceCoords(playState, xy)
callArg(playState, arg, eval, data)
mainCall(playState)
playState$call
).
updateMainCall(playState)
main.function
, or by
guessing. This allows callArg()
to work correctly;
it should be called if playState$call
is replaced.
playReplot(playState)
playNewPlot
should be used instead.
playReplot
is triggered when zooming,
editing plot settings, removing annotations, etc.
playNewPlot(playState)
playReplot
.
Note: playNewPlot
is triggered when the call text
is edited manually in the GUI.
xyData(playState, space)
plotCoords
to generate plot locations;
new methods can be defined for non-standard plot types.
xyCoords(playState, space)
xyData
, converted to numeric coordinates.
getDataArg(playState, eval)
data
argument to the plot call, or from a with()
block.
Felix Andrews felix@nfrac.org
playwith
,
playState
,
convertFromDevicePixels
if (interactive()) { demo(package = "playwith") }