Ephemeral theme arg (#484)

* ephemeral theme argument

* docs

* vignette

* news

* add test

Author: grantmcdermott

NEWS.md

@@ -22,6 +22,9 @@ where the formatting is also better._
   `boxplot(x)`. (#454 @zeileis)
 - `type_errorbar()` and `type_point_range()` get a `dodge` argument.
   (#461 @vincentarelbundock)
+- The new `tinyplot(..., theme = <theme>)` argument enables users to invoke
+  ephemeral themes as an alternative to the persistent themes that follow
+  `tinytheme(<theme>)`. (#483 @grantmcdermott)
 
 ### Bug fixes
 

R/tinyplot.R

@@ -349,6 +349,9 @@
 #'  `width` (above) apply, e.g. will default to `tpar("file.height")` if not
 #'  specified.
 #' @param asp the y/xy/x aspect ratio, see `plot.window`.
+#' @param theme keyword string (e.g. `"clean"`) or list defining a theme. Passed
+#'  on to [`tinytheme`], but reset upon exit so that the theme effect is only
+#'  temporary. Useful for invoking ephemeral themes. 
 #' @param ... other graphical parameters. If `type` is a character specification
 #'   (such as `"hist"`) then any argument names that match those from the corresponding
 #'   `type_*()` function (such as \code{\link{type_hist}}) are passed on to that.
@@ -634,6 +637,7 @@ tinyplot.default = function(
     width = NULL,
     height = NULL,
     asp = NA,
+    theme = NULL,
     ...) {
 
 
@@ -674,6 +678,22 @@ tinyplot.default = function(
   }
   set_saved_par(when = "before", opar)
 
+  # Ephemeral theme
+  if (!is.null(theme)) {
+    # browser()
+    if (is.character(theme) && length(theme) == 1) {
+      tinytheme(theme)
+    } else if (is.list(theme)) {
+      do.call(tinytheme, theme)
+    } else {
+      warning('Argument `theme` must be a character of length 1 (e.g. "clean"), or a list. Ignoring.')
+    }
+    dtheme = theme_default
+    otheme = opar[names(dtheme)]
+
+    on.exit(do.call(tinytheme, otheme), add = TRUE)
+  }
+
 
   #
   ## devices and files -----

R/tinytheme.R

@@ -34,8 +34,11 @@
 #' @details
 #' Sets a list of graphical parameters using `tpar()`
 #'
+#' Note that themes are persistent and will be applied to all subsequent plots.
 #' To reset the theme to default settings (no customization), call `tinytheme()`
-#' without arguments.
+#' without arguments. Altenatively, invoke the `tinyplot(..., theme = <theme>)`
+#' argument for an ephemeral theme that is automatically reset at the end of the
+#' plot call.
 #' 
 #' **Caveat emptor:** Themes are a somewhat experimental feature of `tinyplot`.
 #' While we feel confident that themes should work as expected for most
@@ -65,6 +68,9 @@
 #' # Set a theme
 #' tinytheme("bw")
 #' p()
+#' 
+#' #  A set theme is persistent and will apply to subsequent plots
+#' tinyplot(0:10)
 #'
 #' # Try a different theme
 #' tinytheme("dark")
@@ -86,6 +92,10 @@
 #' tinytheme()
 #' p()
 #' 
+#' # For an ephemeral theme, use `tinyplot(..., theme = <theme>)` directly
+#' tinyplot(0:10, theme = "clean", main = "This theme is ephemeral")
+#' tinyplot(10:0, main = "See, no more theme")
+#' 
 #' # Themes showcase
 #' ## We'll use a slightly more intricate plot (long y-axis labs and facets)
 #' ## to demonstrate dynamic margin adjustment etc.

inst/tinytest/_tinysnapshot/tinytheme_ephemeral.svg

@@ -3,7 +3,6 @@ using("tinysnapshot")
 
 tinytheme()
 
-
 thms = eval(formals(tinytheme)$theme)
 
 for (thm in thms) {
@@ -152,3 +151,19 @@ expect_snapshot_plot(f, label = "tinytheme_dynamic_clean_spineplot")
 ## reset
 
 tinytheme()
+
+
+#
+## ephemeral theme
+
+f = function() {
+  opar = par(mfrow = c(1, 2))
+  plt(Sepal.Length ~ Petal.Length | Species, data = iris,
+      main = "Ephemeral theme", theme = "clean", legend = FALSE)
+  plt_add(type = "lm")
+  plt(Sepal.Length ~ Petal.Length | Species, data = iris,
+      main = "Revert to old theme", legend = FALSE)
+  plt_add(type = "lm")
+  par(opar)
+}
+expect_snapshot_plot(f, label = "tinytheme_ephemeral")

inst/tinytest/test-tinytheme.R

@@ -83,6 +83,20 @@ tinytheme()
 tinyplot(mpg ~ hp, data = mtcars, main = "Fuel efficiency vs. horsepower")
 ```
 
+### Aside: ephemeral themes
+
+We expect that users will generally want to set a persistent theme for all
+(most) of their plots. But it is also possible to set a ephemeral theme for a
+particular plot by calling the `tinyplot(..., theme = <theme>)` argument
+directly.
+
+```{r}
+#| layout-ncol: 2
+tinyplot(mpg ~ hp, data = mtcars, main = "Ephemeral theme", theme = "clean")
+tinyplot(mpg ~ hp, data = mtcars, main = "Back to the default")
+```
+
+
 
 ### Gallery