playwidget: Add a widget to play animations

Description

This is a widget that can be put in a web page to allow animations with or without Shiny.

Usage

playwidget(sceneId, controls,
            start = 0, stop = Inf, interval = 0.05, rate = 1,
            components = c("Reverse", "Play", "Slower", "Faster",
                           "Reset", "Slider", "Label"),
            loop = TRUE,
            step = 1, labels = NULL,
            precision = 3,
            elementId = NULL, respondTo = NULL,
            reinit = NULL,
            buttonLabels = components, pause = "Pause",
            height = 40,
            ...)

Value

A widget suitable for use in an Rmarkdown-generated web page, or elsewhere.

Arguments

sceneId: The HTML id of the RGL scene being controlled, or an object. See the Details below.
controls: A single "rglControl" object, e.g. propertyControl, or a list of several.
start, stop: The starting and stopping values of the animation. If labels is supplied stop will default to step through the labels.
interval: The requested interval (in seconds) between updates. Updates may occur at longer intervals.
rate: The number of units of “nominal” time per real world second.
components: Which components should be displayed? See Details below.
loop: When the player reaches the end of the interval, should it loop back to the beginning?
step: Step size in the slider.
labels: Optional labels to use, corresponding to slider steps. Set to NULL for auto-generated labels.
precision: If labels=NULL, the precision to use when displaying timer values.
elementId: The HTML id of the generated widget, containing buttons, slider, etc.
respondTo: The HTML ID of a Shiny input control (e.g. a sliderInput control) to respond to.
reinit: A vector of ids that will need re-initialization before being drawn again.
buttonLabels, pause: These are the labels that will be shown on the buttons if they are displayed. pause will be shown on the "Play" button while playing.
height: The height of the widget in pixels. In a pipe, this is a relative height.
...: Additional arguments to pass to to htmlwidgets::createWidget.

Appearance

The appearance of the controls is set by the stylesheet in system.file("htmlwidgets/lib/rglClass/rgl.css").

The overall widget is of class rglPlayer, with id set according to elementId.

The buttons are of HTML class rgl-button, the slider is of class rgl-slider, and the label is of class rgl-label. Each element has an id prefixed by the widget id, e.g. elementId-button-Reverse, elementId-slider, etc. (where elementId should be replaced by the actual id).

The reinit parameter handles the case where an object needs re-initialization after each change. For example, plane objects may need this if their intersection with the bounding box changes shape. Note that re-initialization is generally incompatible with the vertexControl as it modifies values which are set during initialization.

Author

Duncan Murdoch

Details

The components are buttons to control the animation, a slider for manual control, and a label to show the current value. They will be displayed in the order given in components. Not all need be included.

The buttons have the following behaviour:

Reverse: Reverse the direction.
Play: Play the animation.
Slower: Decrease the playing speed.
Faster: Increase the playing speed.
Reset: Stop the animation and reset to the start value.

If respondTo is used, no components are shown, as it is assumed Shiny (or whatever control is being referenced) will provide the UI components.

The sceneId component can be another playwidget, a rglwidget result, or a result of htmltools::tags or htmltools::tagList. This allows you to use a magrittr-style “pipe” command to join an rglwidget with one or more playwidgets. If a playwidget comes first, sceneId should be set to NA. If the rglwidget does not come first, previous values should be piped into its controllers argument. Other HTML code (including other widgets) can be used in the chain if wrapped in htmltools::tagList.

Each control should inherit from "rglControl". They can have the following components in addition to any private ones:

labels: default labels for the slider.
param: values to include on the slider.
dependencies: additional HTML dependencies to include, after the default rglwidgetClass.

Examples

Run this code

saveopts <- options(rgl.useNULL = TRUE)

objid <- plot3d(1:10, 1:10, rnorm(10), col=c("red", "red"), type = "s")["data"]

control <- ageControl(value=0,
             births=1:10,
             ages = c(-5,0,5),
             colors = c("green", "yellow", "red"),
             objids = objid)

# \donttest{
# This example uses explicit names
rglwidget(elementId = "theplot", controllers = "theplayer",
          height = 300, width = 300)
playwidget("theplot", control, start = -5, stop = 5,
           rate = 3, elementId = "theplayer",
           components = c("Play", "Slider"))
# }

# This example uses pipes, and can skip the names

widget <- rglwidget(height = 300, width = 300) %>%
playwidget(control, start = -5, stop = 5,
           rate = 3, components = c("Play", "Slider"))
if (interactive() || in_pkgdown_example())
  widget

options(saveopts)

Run the code above in your browser using DataLab