New theme option to put panel/grid on top of data

Closes tidyverse#551

Author: noamross

NEWS

@@ -1,3 +1,9 @@
+NEW FEATURES
+
+* new theme setting `panel.ontop` (logical) allows placing background elements
+  (e.g., gridlines) on top of data. Usually used with blank or transparent
+  `panel.background`.  (@noamross. #551)
+
 ggplot2 1.0.0
 ----------------------------------------------------------------
 

R/facet-grid-.r

@@ -352,7 +352,12 @@ facet_panels.grid <- function(facet, panel, coord, theme, geom_grobs) {
     bg <- coord_render_bg(coord, panel$range[[i]], theme)
 
     geom_grobs <- lapply(geom_grobs, "[[", i)
-    panel_grobs <- c(list(bg), geom_grobs, list(fg))
+
+    if(theme$panel.ontop) {
+      panel_grobs <- c(geom_grobs, list(bg), list(fg))
+    } else {
+      panel_grobs <- c(list(bg), geom_grobs, list(fg))
+    }
 
     gTree(children = do.call("gList", panel_grobs))
   })

R/facet-null.r

@@ -46,7 +46,12 @@ facet_render.null <- function(facet, panel, coord, theme, geom_grobs) {
 
   # Flatten layers - we know there's only one panel
   geom_grobs <- lapply(geom_grobs, "[[", 1)
-  panel_grobs <- c(list(bg), geom_grobs, list(fg))
+
+  if(theme$panel.ontop) {
+    panel_grobs <- c(geom_grobs, list(bg), list(fg))
+  } else {
+    panel_grobs <- c(list(bg), geom_grobs, list(fg))
+  }
 
   panel_grob <- gTree(children = do.call("gList", panel_grobs))
   axis_h <- coord_render_axis_h(coord, range, theme)

R/facet-wrap.r

@@ -197,7 +197,12 @@ facet_panels.wrap <- function(facet, panel, coord, theme, geom_grobs) {
     bg <- coord_render_bg(coord, panel$range[[i]], theme)
 
     geom_grobs <- lapply(geom_grobs, "[[", i)
-    panel_grobs <- c(list(bg), geom_grobs, list(fg))
+
+    if(theme$panel.ontop) {
+      panel_grobs <- c(geom_grobs, list(bg), list(fg))
+    } else {
+      panel_grobs <- c(list(bg), geom_grobs, list(fg))
+    }
 
     ggname(paste("panel", i, sep = "-"),
       gTree(children = do.call("gList", panel_grobs)))

R/theme-defaults.r

@@ -95,6 +95,7 @@ theme_grey <- function(base_size = 12, base_family = "") {
     panel.margin =       unit(0.25, "lines"),
     panel.margin.x =     NULL,
     panel.margin.y =     NULL,
+    panel.ontop    =     FALSE,
 
     strip.background =   element_rect(fill = "grey80", colour = NA),
     strip.text.x =       element_text(),

R/theme-elements.r

@@ -312,6 +312,7 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
   panel.grid.major.y  = el_def("element_line", "panel.grid.major"),
   panel.grid.minor.x  = el_def("element_line", "panel.grid.minor"),
   panel.grid.minor.y  = el_def("element_line", "panel.grid.minor"),
+  panel.ontop         = el_def("logical"),
 
   strip.background    = el_def("element_rect", "rect"),
   strip.text.x        = el_def("element_text", "strip.text"),

R/theme.r

@@ -153,6 +153,9 @@ print.theme <- function(x, ...) str(x)
 #'                    (\code{element_line}; inherits from \code{panel.grid.minor}) \cr
 #'   panel.grid.minor.y \tab horizontal minor grid lines
 #'                    (\code{element_line}; inherits from \code{panel.grid.minor}) \cr
+#'   panel.ontop        \tab option to place the panel (background, gridlines)
+#'                           over the data layers.  Usually used with a transparent
+#'                           or blank \code{panel.background}. (\code{logical}) \cr
 #'
 #'   plot.background  \tab background of the entire plot
 #'                    (\code{element_rect}; inherits from \code{rect}) \cr
@@ -423,7 +426,7 @@ add_theme <- function(t1, t2, t2name) {
       # If x is NULL or element_blank, then just assign it y
       x <- y
     } else if (is.null(y) || is.character(y) || is.numeric(y) ||
-               inherits(y, "element_blank")) {
+               is.logical(y) || inherits(y, "element_blank")) {
       # If y is NULL, or a string or numeric vector, or is element_blank, just replace x
       x <- y
     } else {

man/theme.Rd

@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.0.0): do not edit by hand
+% Generated by roxygen2 (4.0.1): do not edit by hand
 \name{theme}
 \alias{theme}
 \title{Set theme elements}
@@ -131,6 +131,9 @@ The individual theme elements are:
                    (\code{element_line}; inherits from \code{panel.grid.minor}) \cr
   panel.grid.minor.y \tab horizontal minor grid lines
                    (\code{element_line}; inherits from \code{panel.grid.minor}) \cr
+  panel.ontop        \tab option to place the panel (background, gridlines)
+                          over the data layers.  Usually used with a transparent
+                          or blank \code{panel.background}. (\code{logical}) \cr
 
   plot.background  \tab background of the entire plot
                    (\code{element_rect}; inherits from \code{rect}) \cr