Make separate parameter for caption position. Closes tidyverse#3252.

Author: clauswilke

NEWS.md

@@ -21,6 +21,11 @@
 
 * Changed `theme_grey()` setting for legend key so that it creates no 
   border (`NA`) rather than drawing a white one. (@annennenne, #3180)
+  
+* Themes have gained two new parameters, `plot.title.position` and 
+  `plot.caption.position`, that can be used to customize how plot
+  title/subtitle and plot caption are positioned relative to the overall plot
+  (@clauswilke, #3252).
 
 * Added function `ggplot_add.by()` for lists created with `by()` (#2734, @Maschette)
 

R/plot-build.r

@@ -261,24 +261,34 @@ ggplot_gtable.ggplot_built <- function(data) {
   caption <- element_render(theme, "plot.caption", plot$labels$caption, margin_y = TRUE)
   caption_height <- grobHeight(caption)
 
-  # positioning of title, subtitle, and caption is governed by plot.title.position
+  # positioning of title and subtitle is governed by plot.title.position
+  # positioning of caption is governed by plot.caption.position
   #   "panel" means align to the panel(s)
   #   "plot" means align to the entire plot (except margins and tag)
   title_pos <- theme$plot.title.position %||% "panel"
-
   if (!(title_pos %in% c("panel", "plot"))) {
     stop('plot.title.position should be either "panel" or "plot".', call. = FALSE)
   }
+  caption_pos <- theme$plot.caption.position %||% "panel"
+  if (!(caption_pos %in% c("panel", "plot"))) {
+    stop('plot.caption.position should be either "panel" or "plot".', call. = FALSE)
+  }
 
+  pans <- plot_table$layout[grepl("^panel", plot_table$layout$name), , drop = FALSE]
   if (title_pos == "panel") {
-    pans <- plot_table$layout[grepl("^panel", plot_table$layout$name), ,
-      drop = FALSE]
     title_l = min(pans$l)
     title_r = max(pans$r)
   } else {
     title_l = 1
     title_r = ncol(plot_table)
   }
+  if (caption_pos == "panel") {
+    caption_l = min(pans$l)
+    caption_r = max(pans$r)
+  } else {
+    caption_l = 1
+    caption_r = ncol(plot_table)
+  }
 
   plot_table <- gtable_add_rows(plot_table, subtitle_height, pos = 0)
   plot_table <- gtable_add_grob(plot_table, subtitle, name = "subtitle",
@@ -290,7 +300,7 @@ ggplot_gtable.ggplot_built <- function(data) {
 
   plot_table <- gtable_add_rows(plot_table, caption_height, pos = -1)
   plot_table <- gtable_add_grob(plot_table, caption, name = "caption",
-    t = -1, b = -1, l = title_l, r = title_r, clip = "off")
+    t = -1, b = -1, l = caption_l, r = caption_r, clip = "off")
 
   plot_table <- gtable_add_rows(plot_table, unit(0, 'pt'), pos = 0)
   plot_table <- gtable_add_cols(plot_table, unit(0, 'pt'), pos = 0)

R/theme-defaults.r

@@ -224,6 +224,7 @@ theme_grey <- function(base_size = 11, base_family = "",
                            hjust = 1, vjust = 1,
                            margin = margin(t = half_line)
                          ),
+    plot.caption.position = "panel",
     plot.tag =           element_text(
                            size = rel(1.2),
                            hjust = 0.5, vjust = 0.5
@@ -498,6 +499,7 @@ theme_void <- function(base_size = 11, base_family = "",
                            hjust = 1, vjust = 1,
                            margin = margin(t = half_line)
                          ),
+    plot.caption.position = "panel",
     plot.tag =           element_text(
                            size = rel(1.2),
                            hjust = 0.5, vjust = 0.5
@@ -627,6 +629,7 @@ theme_test <- function(base_size = 11, base_family = "",
                            hjust = 1, vjust = 1,
                            margin = margin(t = half_line)
                          ),
+    plot.caption.position = "panel",
     plot.tag =           element_text(
                            size = rel(1.2),
                            hjust = 0.5, vjust = 0.5

R/theme-elements.r

@@ -373,6 +373,7 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
   plot.title.position = el_def("character"),
   plot.subtitle       = el_def("element_text", "title"),
   plot.caption        = el_def("element_text", "title"),
+  plot.caption.position = el_def("character"),
   plot.tag            = el_def("element_text", "title"),
   plot.tag.position   = el_def("character"),  # Need to also accept numbers
   plot.margin         = el_def("margin"),

R/theme.r

@@ -124,6 +124,12 @@
 #'   inherits from `title`) left-aligned by default
 #' @param plot.caption caption below the plot (text appearance)
 #'   ([element_text()]; inherits from `title`) right-aligned by default
+#' @param plot.title.position,plot.caption.position Alignment of the plot title/subtitle
+#'   and caption.  The setting for `plot.title.position` applies to both
+#'   the title and the subtitle. A value of "panel" (the default) means that
+#'   titles and/or caption are aligned to the plot panels. A value of "plot" means
+#'   that titles and/or caption are aligned to the entire plot (minus any space
+#'   for margins and plot tag).
 #' @param plot.tag upper-left label to identify a plot (text appearance)
 #'   ([element_text()]; inherits from `title`) left-aligned by default
 #' @param plot.tag.position The position of the tag as a string ("topleft",
@@ -334,8 +340,10 @@ theme <- function(line,
                   panel.ontop,
                   plot.background,
                   plot.title,
+                  plot.title.position,
                   plot.subtitle,
                   plot.caption,
+                  plot.caption.position,
                   plot.tag,
                   plot.tag.position,
                   plot.margin,