New spacing and margins root theme elements (#5631)

* add missing `calc_element()`s

* declare new theme elements

* rewire inheritance

* Use theme for `legend.ticks.length`

* fix bug

* adapt theme_test()

* temp

* add visual tests

* fix panel spacing in vignette

* use `margin()` in vignette

* reformat news bullet

Author: teunbrand

NEWS.md

@@ -33,6 +33,8 @@
   cannot be transformed (@teunbrand, #3171).
 * `stat_density()` has the new computed variable: `wdensity`, which is
   calculated as the density times the sum of weights (@teunbrand, #4176).
+* `theme()` gets new `spacing` and `margins` arguments that all other spacings
+  and (non-text) margins inherit from (@teunbrand, #5622).
 
 # ggplot2 3.5.1
 

R/facet-grid-.R

@@ -412,10 +412,10 @@ FacetGrid <- ggproto("FacetGrid", Facet,
       panel_widths, panel_heights, respect = respect, clip = coord$clip, z = mtx(1))
     panel_table$layout$name <- paste0('panel-', rep(seq_len(nrow), ncol), '-', rep(seq_len(ncol), each = nrow))
 
-    panel_table <- gtable_add_col_space(panel_table,
-      theme$panel.spacing.x %||% theme$panel.spacing)
-    panel_table <- gtable_add_row_space(panel_table,
-      theme$panel.spacing.y %||% theme$panel.spacing)
+    spacing_x <- calc_element("panel.spacing.x", theme)
+    spacing_y <- calc_element("panel.spacing.y", theme)
+    panel_table <- gtable_add_col_space(panel_table, spacing_x)
+    panel_table <- gtable_add_row_space(panel_table, spacing_y)
 
     # Add axes
     if (params$draw_axes$x) {
@@ -445,7 +445,7 @@ FacetGrid <- ggproto("FacetGrid", Facet,
     switch_y <- !is.null(params$switch) && params$switch %in% c("both", "y")
     inside_x <- (theme$strip.placement.x %||% theme$strip.placement %||% "inside") == "inside"
     inside_y <- (theme$strip.placement.y %||% theme$strip.placement %||% "inside") == "inside"
-    strip_padding <- convertUnit(theme$strip.switch.pad.grid, "cm")
+    strip_padding <- convertUnit(calc_element("strip.switch.pad.grid", theme), "cm")
     panel_pos_col <- panel_cols(panel_table)
     if (switch_x) {
       if (!is.null(strips$x$bottom)) {

R/facet-wrap.R

@@ -325,10 +325,9 @@ FacetWrap <- ggproto("FacetWrap", Facet,
      heights = unit(rep(abs(aspect_ratio), nrow), "null"), respect = respect, clip = coord$clip, z = matrix(1, ncol = ncol, nrow = nrow))
     panel_table$layout$name <- paste0('panel-', rep(seq_len(ncol), nrow), '-', rep(seq_len(nrow), each = ncol))
 
-    panel_table <- gtable_add_col_space(panel_table,
-      theme$panel.spacing.x %||% theme$panel.spacing)
-    panel_table <- gtable_add_row_space(panel_table,
-      theme$panel.spacing.y %||% theme$panel.spacing)
+
+    panel_table <- gtable_add_col_space(panel_table, calc_element("panel.spacing.x", theme))
+    panel_table <- gtable_add_row_space(panel_table, calc_element("panel.spacing.y", theme))
 
     # Add axes
     axis_mat_x_top <- empty_table
@@ -442,7 +441,7 @@ FacetWrap <- ggproto("FacetWrap", Facet,
     axis_size   <- panel_table$sizes
     panel_table <- panel_table$panels
 
-    strip_padding <- convertUnit(theme$strip.switch.pad.wrap, "cm")
+    strip_padding <- convertUnit(calc_element("strip.switch.pad.wrap", theme), "cm")
     strip_name <- paste0("strip-", substr(params$strip.position, 1, 1))
     strip_mat <- empty_table
     strip_mat[panel_pos] <- unlist(unname(strips), recursive = FALSE)[[params$strip.position]]

R/guide-legend.R

@@ -313,8 +313,8 @@ GuideLegend <- ggproto(
       arg_match0(title_position, .trbl, arg_nm = "legend.title.position")
 
     # Set default spacing
-    theme$legend.key.spacing <- theme$legend.key.spacing %||% unit(5.5, "pt")
-    gap <- calc_element("legend.key.spacing", theme)
+    theme$legend.key.spacing <- calc_element("legend.key.spacing", theme)
+    gap <- theme$legend.key.spacing
 
     # For backward compatibility, default vertical spacing is no spacing
     if (params$direction == "vertical") {

R/guides-.R

@@ -608,7 +608,7 @@ Guides <- ggproto(
     box_xjust <- box_just[1]
     box_yjust <- box_just[2]
 
-    margin <- theme$legend.box.margin %||% margin()
+    margin <- calc_element("legend.box.margin", theme) %||% margin()
 
     # setting that is different for vertical and horizontal guide-boxes.
     if (identical(theme$legend.box, "horizontal")) {

R/plot-build.R

@@ -261,10 +261,8 @@ ggplot_gtable.ggplot_built <- function(data) {
   plot_table <- table_add_tag(plot_table, plot$labels$tag, theme)
 
   # Margins
-  plot_table <- gtable_add_rows(plot_table, theme$plot.margin[1], pos = 0)
-  plot_table <- gtable_add_cols(plot_table, theme$plot.margin[2])
-  plot_table <- gtable_add_rows(plot_table, theme$plot.margin[3])
-  plot_table <- gtable_add_cols(plot_table, theme$plot.margin[4], pos = 0)
+  plot_margin <- calc_element("plot.margin", theme)
+  plot_table  <- gtable_add_padding(plot_table, plot_margin)
 
   if (inherits(theme$plot.background, "element")) {
     plot_table <- gtable_add_grob(plot_table,
@@ -443,7 +441,7 @@ table_add_legends <- function(table, legends, theme) {
   empty <- vapply(legends, is.zero, logical(1))
   widths[!empty]  <- lapply(legends[!empty], gtable_width)
   heights[!empty] <- lapply(legends[!empty], gtable_height)
-  spacing <- theme$legend.box.spacing %||% unit(0.2, "cm")
+  spacing <- calc_element("legend.box.spacing", theme) %||% unit(0.2, "cm")
 
   # If legend is missing, set spacing to zero for that legend
   zero    <- unit(0, "pt")

R/theme-defaults.R

@@ -133,6 +133,8 @@ theme_grey <- function(base_size = 11, base_family = "",
                             lineheight = 0.9, hjust = 0.5, vjust = 0.5, angle = 0,
                             margin = margin(), debug = FALSE
                          ),
+    spacing = unit(half_line, "pt"),
+    margins = margin(half_line, half_line, half_line, half_line),
 
     axis.line =          element_blank(),
     axis.line.x =        NULL,
@@ -145,7 +147,7 @@ theme_grey <- function(base_size = 11, base_family = "",
     axis.text.r =        element_text(margin = margin(l = 0.8 * half_line / 2, r = 0.8 * half_line / 2),
                                       hjust = 0.5),
     axis.ticks =         element_line(colour = "grey20"),
-    axis.ticks.length =  unit(half_line / 2, "pt"),
+    axis.ticks.length =  rel(0.5),
     axis.ticks.length.x = NULL,
     axis.ticks.length.x.top = NULL,
     axis.ticks.length.x.bottom = NULL,
@@ -173,31 +175,31 @@ theme_grey <- function(base_size = 11, base_family = "",
                          ),
 
     legend.background =  element_rect(colour = NA),
-    legend.spacing =     unit(2 * half_line, "pt"),
+    legend.spacing =     rel(2),
     legend.spacing.x =    NULL,
     legend.spacing.y =    NULL,
-    legend.margin =      margin(half_line, half_line, half_line, half_line),
+    legend.margin =      NULL,
     legend.key =         NULL,
     legend.key.size =    unit(1.2, "lines"),
     legend.key.height =  NULL,
     legend.key.width =   NULL,
-    legend.key.spacing = unit(half_line, "pt"),
+    legend.key.spacing = NULL,
     legend.text =        element_text(size = rel(0.8)),
     legend.title =       element_text(hjust = 0),
     legend.ticks.length = rel(0.2),
     legend.position =    "right",
     legend.direction =   NULL,
     legend.justification = "center",
     legend.box =         NULL,
-    legend.box.margin =  margin(0, 0, 0, 0, "cm"),
+    legend.box.margin =  rel(0),
     legend.box.background = element_blank(),
-    legend.box.spacing = unit(2 * half_line, "pt"),
+    legend.box.spacing = rel(2),
 
     panel.background =   element_rect(fill = "grey92", colour = NA),
     panel.border =       element_blank(),
     panel.grid =         element_line(colour = "white"),
     panel.grid.minor =   element_line(linewidth = rel(0.5)),
-    panel.spacing =      unit(half_line, "pt"),
+    panel.spacing =      NULL,
     panel.spacing.x =    NULL,
     panel.spacing.y =    NULL,
     panel.ontop    =     FALSE,
@@ -240,7 +242,7 @@ theme_grey <- function(base_size = 11, base_family = "",
                            hjust = 0.5, vjust = 0.5
                          ),
     plot.tag.position =  'topleft',
-    plot.margin =        margin(half_line, half_line, half_line, half_line),
+    plot.margin =        NULL,
 
     complete = TRUE
   )
@@ -466,30 +468,35 @@ theme_void <- function(base_size = 11, base_family = "",
                             lineheight = 0.9, hjust = 0.5, vjust = 0.5, angle = 0,
                             margin = margin(), debug = FALSE
                          ),
+    spacing =            unit(half_line, "pt"),
+    margins =            margin(half_line, half_line, half_line, half_line),
     axis.text =          element_blank(),
     axis.title =         element_blank(),
-    axis.ticks.length =  unit(0, "pt"),
+    axis.ticks.length =  rel(0),
     axis.ticks.length.x = NULL,
     axis.ticks.length.x.top = NULL,
     axis.ticks.length.x.bottom = NULL,
     axis.ticks.length.y = NULL,
     axis.ticks.length.y.left = NULL,
     axis.ticks.length.y.right = NULL,
-    axis.minor.ticks.length = unit(0, "pt"),
+    axis.minor.ticks.length = NULL,
     legend.box =         NULL,
     legend.key.size =    unit(1.2, "lines"),
     legend.position =    "right",
     legend.text =        element_text(size = rel(0.8)),
     legend.title =       element_text(hjust = 0),
-    legend.key.spacing = unit(half_line, "pt"),
+    legend.key.spacing = rel(1),
+    legend.margin =      rel(0),
+    legend.box.margin =  rel(0),
+    legend.box.spacing = unit(0.2, "cm"),
     legend.ticks.length = rel(0.2),
     strip.clip =         "inherit",
     strip.text =         element_text(size = rel(0.8)),
-    strip.switch.pad.grid = unit(half_line / 2, "pt"),
-    strip.switch.pad.wrap = unit(half_line / 2, "pt"),
+    strip.switch.pad.grid = rel(0.5),
+    strip.switch.pad.wrap = rel(0.5),
     panel.ontop =        FALSE,
-    panel.spacing =      unit(half_line, "pt"),
-    plot.margin =        unit(c(0, 0, 0, 0), "lines"),
+    panel.spacing =      NULL,
+    plot.margin =        rel(0),
     plot.title =         element_text(
                            size = rel(1.2),
                            hjust = 0, vjust = 1,
@@ -542,6 +549,8 @@ theme_test <- function(base_size = 11, base_family = "",
                             lineheight = 0.9, hjust = 0.5, vjust = 0.5, angle = 0,
                             margin = margin(), debug = FALSE
                          ),
+    spacing = unit(half_line, "pt"),
+    margins = margin(half_line, half_line, half_line, half_line),
 
     axis.line =          element_blank(),
     axis.line.x =        NULL,
@@ -552,7 +561,7 @@ theme_test <- function(base_size = 11, base_family = "",
     axis.text.y =        element_text(margin = margin(r = 0.8 * half_line / 2), hjust = 1),
     axis.text.y.right =  element_text(margin = margin(l = 0.8 * half_line / 2), hjust = 0),
     axis.ticks =         element_line(colour = "grey20"),
-    axis.ticks.length =  unit(half_line / 2, "pt"),
+    axis.ticks.length =  rel(0.5),
     axis.ticks.length.x = NULL,
     axis.ticks.length.x.top = NULL,
     axis.ticks.length.x.bottom = NULL,
@@ -580,15 +589,15 @@ theme_test <- function(base_size = 11, base_family = "",
                          ),
 
     legend.background =  element_rect(colour = NA),
-    legend.spacing =     unit(2 * half_line, "pt"),
+    legend.spacing =     rel(2),
     legend.spacing.x =   NULL,
     legend.spacing.y =   NULL,
     legend.margin =      margin(0, 0, 0, 0, "cm"),
     legend.key =         NULL,
     legend.key.size =    unit(1.2, "lines"),
     legend.key.height =  NULL,
     legend.key.width =   NULL,
-    legend.key.spacing = unit(half_line, "pt"),
+    legend.key.spacing = NULL,
     legend.key.spacing.x = NULL,
     legend.key.spacing.y = NULL,
     legend.text =        element_text(size = rel(0.8)),
@@ -600,13 +609,13 @@ theme_test <- function(base_size = 11, base_family = "",
     legend.box =         NULL,
     legend.box.margin =  margin(0, 0, 0, 0, "cm"),
     legend.box.background = element_blank(),
-    legend.box.spacing = unit(2 * half_line, "pt"),
+    legend.box.spacing = rel(2),
 
     panel.background =   element_rect(fill = "white", colour = NA),
     panel.border =       element_rect(fill = NA, colour = "grey20"),
     panel.grid.major =   element_blank(),
     panel.grid.minor =   element_blank(),
-    panel.spacing =      unit(half_line, "pt"),
+    panel.spacing =      NULL,
     panel.spacing.x =    NULL,
     panel.spacing.y =    NULL,
     panel.ontop    =     FALSE,
@@ -624,8 +633,8 @@ theme_test <- function(base_size = 11, base_family = "",
     strip.placement =    "inside",
     strip.placement.x =  NULL,
     strip.placement.y =  NULL,
-    strip.switch.pad.grid = unit(half_line / 2, "pt"),
-    strip.switch.pad.wrap = unit(half_line / 2, "pt"),
+    strip.switch.pad.grid = rel(0.5),
+    strip.switch.pad.wrap = rel(0.5),
 
     plot.background =    element_rect(colour = "white"),
     plot.title =         element_text(
@@ -649,7 +658,7 @@ theme_test <- function(base_size = 11, base_family = "",
                            hjust = 0.5, vjust = 0.5
                          ),
     plot.tag.position =  'topleft',
-    plot.margin =        margin(half_line, half_line, half_line, half_line),
+    plot.margin =        NULL,
 
     complete = TRUE
   )

R/theme-elements.R

@@ -419,11 +419,14 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
   rect                = el_def("element_rect"),
   text                = el_def("element_text"),
   title               = el_def("element_text", "text"),
+  spacing             = el_def("unit"),
+  margins             = el_def("margin"),
+
   axis.line           = el_def("element_line", "line"),
   axis.text           = el_def("element_text", "text"),
   axis.title          = el_def("element_text", "title"),
   axis.ticks          = el_def("element_line", "line"),
-  legend.key.size     = el_def("unit"),
+  legend.key.size     = el_def(c("unit", "rel"), "spacing"),
   panel.grid          = el_def("element_line", "line"),
   panel.grid.major    = el_def("element_line", "panel.grid"),
   panel.grid.minor    = el_def("element_line", "panel.grid"),
@@ -447,7 +450,7 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
   axis.text.theta     = el_def("element_text", "axis.text.x"),
   axis.text.r         = el_def("element_text", "axis.text.y"),
 
-  axis.ticks.length   = el_def("unit"),
+  axis.ticks.length   = el_def(c("unit", "rel"), "spacing"),
   axis.ticks.length.x = el_def(c("unit", "rel"), "axis.ticks.length"),
   axis.ticks.length.x.top = el_def(c("unit", "rel"), "axis.ticks.length.x"),
   axis.ticks.length.x.bottom = el_def(c("unit", "rel"), "axis.ticks.length.x"),
@@ -503,14 +506,14 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
   ),
 
   legend.background   = el_def("element_rect", "rect"),
-  legend.margin       = el_def("margin"),
-  legend.spacing      = el_def("unit"),
+  legend.margin       = el_def(c("margin", "rel"), "margins"),
+  legend.spacing      = el_def(c("unit", "rel"), "spacing"),
   legend.spacing.x     = el_def(c("unit", "rel"), "legend.spacing"),
   legend.spacing.y     = el_def(c("unit", "rel"), "legend.spacing"),
   legend.key          = el_def("element_rect", "panel.background"),
   legend.key.height   = el_def(c("unit", "rel"), "legend.key.size"),
   legend.key.width    = el_def(c("unit", "rel"), "legend.key.size"),
-  legend.key.spacing  = el_def("unit"),
+  legend.key.spacing  = el_def(c("unit", "rel"), "spacing"),
   legend.key.spacing.x = el_def(c("unit", "rel"), "legend.key.spacing"),
   legend.key.spacing.y = el_def(c("unit", "rel"), "legend.key.spacing"),
   legend.frame        = el_def("element_rect", "rect"),
@@ -552,13 +555,13 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
 
   legend.box          = el_def("character"),
   legend.box.just     = el_def("character"),
-  legend.box.margin   = el_def("margin"),
+  legend.box.margin   = el_def(c("margin", "rel"), "margins"),
   legend.box.background = el_def("element_rect", "rect"),
-  legend.box.spacing  = el_def("unit"),
+  legend.box.spacing  = el_def(c("unit", "rel"), "spacing"),
 
   panel.background    = el_def("element_rect", "rect"),
   panel.border        = el_def("element_rect", "rect"),
-  panel.spacing       = el_def("unit"),
+  panel.spacing       = el_def(c("unit", "rel"), "spacing"),
   panel.spacing.x     = el_def(c("unit", "rel"), "panel.spacing"),
   panel.spacing.y     = el_def(c("unit", "rel"), "panel.spacing"),
   panel.grid.major.x  = el_def("element_line", "panel.grid.major"),
@@ -580,8 +583,8 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
   strip.placement     = el_def("character"),
   strip.placement.x   = el_def("character", "strip.placement"),
   strip.placement.y   = el_def("character", "strip.placement"),
-  strip.switch.pad.grid = el_def("unit"),
-  strip.switch.pad.wrap = el_def("unit"),
+  strip.switch.pad.grid = el_def(c("unit", "rel"), "spacing"),
+  strip.switch.pad.wrap = el_def(c("unit", "rel"), "spacing"),
 
   plot.background     = el_def("element_rect", "rect"),
   plot.title          = el_def("element_text", "title"),
@@ -592,7 +595,7 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
   plot.tag            = el_def("element_text", "title"),
   plot.tag.position   = el_def(c("character", "numeric", "integer")),  # Need to also accept numbers
   plot.tag.location   = el_def("character"),
-  plot.margin         = el_def("margin"),
+  plot.margin         = el_def(c("margin", "rel"), "margins"),
 
   aspect.ratio        = el_def(c("numeric", "integer"))
 )