Description Details Device management Common user commands Interaction Working with the display Working with the call Working with data Author(s) See Also Examples
The playwith Application Programming Interface.
playwith
plots (incorporating a plot, window and device)
are represented by a playState
object.
The following sections list 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.
These are similar to dev.set
etc.
playDevCur()
returns the current or last
active playState
– this is not necessarily the active
graphics device.
playDevList()
lists all open playState
s.
playDevSet(playState)
sets the current playState
, and sets the active
graphics device.
playDevOff(playState)
closes the device and window (dev.off()
also
works).
These functions are also available as menu items.
playGetIDs(playState, type, labels)
returns indices (or labels) of currently brushed or labelled data points.
playSetIDs(playState, value, type, space,
add, redraw, pos)
sets which data points are brushed or
labelled. type
defaults to "brushed"
;
space
is ignored unless type = "labelled"
.
playClear(playState, type, redraw)
remove one or more of the 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)
reverts the last change any annotations (including the set of labelled and brushed data points).
updateLinkedSubscribers(playState, redraw)
triggers a redraw of any linked plots.
playUnlink(playState)
removes links from the given plot to any other plots (for linked brushing).
playSourceCode(playState)
returns (deparsed) R code to reproduce the current plot display.
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)
interactively select data from the plot (one point or a whole region).
playPointInput(playState, prompt)
prompt for
a click on the plot. Similar to locator
.
playLineInput(playState, prompt,
scales)
prompt to drag a line.
playRectInput(playState, prompt,
scales)
prompt to drag a rectangular region.
playPrompt(playState, text)
sets the
statusbar text. Pass NULL
to reset. The GUI is
frozen when the prompt is set and unfrozen when reset.
playFreezeGUI(playState)
,
playThawGUI(playState)
disables or re-enables the GUI.
playDo(playState, expr, space, clip.off,
return.code)
evalutes the given expression in the given plot space, i.e. after moving to the corresponding grid viewport.
playAnnotate(playState, annot, space, add, redraw)
adds the annotation (a call or expression to draw on the plot) to the list of persistent annotations, and draws them. These will always be drawn after plotting (unless they are removed by the user).
rawXLim(playState, space)
gets or sets the x axis limits, in native coordinates of the given space (viewport).
rawYLim(playState, space)
same as rawXLim
, for y axis limits.
spaceCoordsToDataCoords(playState, xy)
converts raw space (viewport) coordinates to the data scale by applying an inverse log transformation if necessary. If there are no log scales this does nothing.
dataCoordsToSpaceCoords(playState, xy)
converts data coordinates to raw space (viewport) coordinates by applying a log transformation if necessary. If there are no log scales this does nothing.
callArg(playState, arg, eval, data)
gets or sets arguments to the main plot call.
mainCall(playState)
gets or replaces
the main plot call (which is not necessarily the same as
the top-level call, playState$call
).
updateMainCall(playState)
locates the main plot call within the top-level call – by
matching against the given main.function
, or by
guessing. This allows callArg()
to work correctly;
it should be called if playState$call
is replaced.
playReplot(playState)
redraws the plot by evaluating the plot call, and runs
update actions.
This should
be called after changing plot arguments (or annotations if
that requires a redraw). However, if the data has changed
or the type of plot (e.g. the high-level plot function)
has changed, playNewPlot
should be used instead.
playReplot
is triggered when zooming,
editing plot settings, removing annotations, etc.
playNewPlot(playState)
redraws the plot by evaluating the plot call,
updates the main call, runs
init actions (such as detecting whether zooming,
identifying or brushing data points is possible),
as well as running update actions as with
playReplot
.
Note: playNewPlot
is triggered when the call text
is edited manually in the GUI.
xyData(playState, space)
attempts to extract plot data in terms of x and y
locations, but in the original data form (such as factor,
date or time). This uses the generic function
plotCoords
to generate plot locations;
new methods can be defined for non-standard plot types.
xyCoords(playState, space)
same as xyData
, converted to numeric coordinates.
getDataArg(playState, eval)
attempts to extract the underlying data set (typically a
data.frame), which may contain more variables than those
currently plotted. This may come from a data
argument to the plot call, or from a with()
block.
Felix Andrews felix@nfrac.org
playwith
,
playState
,
convertFromDevicePixels
1 2 3 4 5 | if (interactive()) {
demo(package = "playwith")
}
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.