Deprecate legend.title.align and legend.text.align (#5362)

* soft-deprecate `legend.text/title.align` * Remove `legend.text/title.align` from element tree * Absolve default themes * Absolve guides * Don't recommend `legend.title.align` * Add news bullet
tidyverse · Aug 1, 2023 · a747da3 · a747da3
1 parent af4cc02
commit a747da3
Show file tree

Hide file tree

Showing 8 changed files with 38 additions and 33 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -1,8 +1,13 @@
 # ggplot2 (development version)
 
+* The `legend.text.align` and `legend.title.align` arguments in `theme()` are 
+ deprecated. The `hjust` setting of the `legend.text` and `legend.title` 
+ elements continues to fulfil the role of text alignment (@teunbrand, #5347).
+
 * Integers are once again valid input to theme arguments that expect numeric
  input (@teunbrand, #5369)
 
+
 * Nicer error messages for xlim/ylim arguments in coord-* functions
  (@92amartins, #4601, #5297).
 

diff --git a/R/guide-colorbar.R b/R/guide-colorbar.R
@@ -314,9 +314,7 @@ GuideColourbar <- ggproto(
  key.height = "legend.key.height",
  key.width = "legend.key.width",
  text = "legend.text",
- text.align = "legend.text.align",
- theme.title = "legend.title",
- title.align = "legend.title.align"
+ theme.title = "legend.title"
  ),
 
  extract_decor = function(scale, aesthetic, nbin = 300, reverse = FALSE, ...) {

diff --git a/R/guide-legend.R b/R/guide-legend.R
@@ -256,9 +256,7 @@ GuideLegend <- ggproto(
  key.height = "legend.key.height",
  key.width = "legend.key.width",
  text = "legend.text",
- text.align = "legend.text.align",
- theme.title = "legend.title",
- title.align = "legend.title.align"
+ theme.title = "legend.title"
  ),
 
  extract_params = function(scale, params, hashables,
@@ -395,8 +393,7 @@ GuideLegend <- ggproto(
 
  # Title
  title <- combine_elements(params$title.theme, elements$theme.title)
- title$hjust <- params$title.hjust %||% elements$title.align %||%
- title$hjust %||% 0
+ title$hjust <- params$title.hjust %||% title$hjust %||% 0
  title$vjust <- params$title.vjust %||% title$vjust %||% 0.5
  elements$title <- title
 
@@ -421,8 +418,7 @@ GuideLegend <- ggproto(
  is.null(theme$legend.text$vjust)) {
  label$vjust <- NULL
  }
- label$hjust <- params$label.hjust %||% elements$text.align %||%
- label$hjust %||% hjust
+ label$hjust <- params$label.hjust %||% label$hjust %||% hjust
  label$vjust <- params$label.vjust %||% label$vjust %||% vjust
  }
  elements$text <- label

diff --git a/R/theme-defaults.R b/R/theme-defaults.R
@@ -176,9 +176,7 @@ theme_grey <- function(base_size = 11, base_family = "",
  legend.key.height = NULL,
  legend.key.width = NULL,
  legend.text = element_text(size = rel(0.8)),
- legend.text.align = NULL,
  legend.title = element_text(hjust = 0),
- legend.title.align = NULL,
  legend.position = "right",
  legend.direction = NULL,
  legend.justification = "center",
@@ -590,9 +588,7 @@ theme_test <- function(base_size = 11, base_family = "",
  legend.key.height = NULL,
  legend.key.width = NULL,
  legend.text = element_text(size = rel(0.8)),
- legend.text.align = NULL,
  legend.title = element_text(hjust = 0),
- legend.title.align = NULL,
  legend.position = "right",
  legend.direction = NULL,
  legend.justification = "center",

diff --git a/R/theme-elements.R b/R/theme-elements.R
@@ -476,9 +476,7 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
  legend.key.height = el_def("unit", "legend.key.size"),
  legend.key.width = el_def("unit", "legend.key.size"),
  legend.text = el_def("element_text", "text"),
- legend.text.align = el_def(c("numeric", "integer")),
  legend.title = el_def("element_text", "title"),
- legend.title.align = el_def(c("numeric", "integer")),
  legend.position = el_def(c("character", "numeric", "integer")),
  legend.direction = el_def("character"),
  legend.justification = el_def(c("character", "numeric", "integer")),

diff --git a/R/theme.R b/R/theme.R
@@ -71,12 +71,8 @@
 #' `legend.key.size` or can be specified separately
 #' @param legend.text legend item labels ([element_text()]; inherits from
 #' `text`)
-#' @param legend.text.align alignment of legend labels (number from 0 (left) to
-#' 1 (right))
 #' @param legend.title title of legend ([element_text()]; inherits from
 #' `title`)
-#' @param legend.title.align alignment of legend title (number from 0 (left) to
-#' 1 (right))
 #' @param legend.position the position of legends ("none", "left", "right",
 #' "bottom", "top", or two-element numeric vector)
 #' @param legend.direction layout of items in legends ("horizontal" or
@@ -330,9 +326,7 @@ theme <- function(line,
  legend.key.height,
  legend.key.width,
  legend.text,
- legend.text.align,
  legend.title,
- legend.title.align,
  legend.position,
  legend.direction,
  legend.justification,
@@ -419,6 +413,32 @@ theme <- function(line,
  elements$legend.spacing <- elements$legend.margin
  elements$legend.margin <- margin()
  }
+ if (!is.null(elements$legend.title.align)) {
+ deprecate_soft0(
+ "3.5.0", "theme(legend.title.align)",
+ I("theme(legend.title = element_text(hjust))")
+ )
+ if (is.null(elements[["legend.title"]])) {
+ elements$legend.title <- element_text(hjust = elements$legend.title.align)
+ } else {
+ elements$legend.title$hjust <- elements$legend.title$hjust %||%
+ elements$legend.title.align
+ }
+ elements$legend.title.align <- NULL
+ }
+ if (!is.null(elements$legend.text.align)) {
+ deprecate_soft0(
+ "3.5.0", "theme(legend.text.align)",
+ I("theme(legend.text = element_text(hjust))")
+ )
+ if (is.null(elements[["legend.text"]])) {
+ elements$legend.text <- element_text(hjust = elements$legend.text.align)
+ } else {
+ elements$legend.text$hjust <- elements$legend.text$hjust %||%
+ elements$legend.text.align
+ }
+ elements$legend.text.align <- NULL
+ }
 
  # If complete theme set all non-blank elements to inherit from blanks
  if (complete) {

diff --git a/man/theme.Rd b/man/theme.Rd
diff --git a/vignettes/articles/faq-customising.Rmd b/vignettes/articles/faq-customising.Rmd
@@ -130,7 +130,7 @@ ggplot(mpg, aes(x = hwy, y = cty, color = drv)) +
 ```
 
 Note that the legend title is no longer aligned with the keys with this approach.
-You can also shift it over with `legend.title.align`.
+You can also shift it over with the `hjust` setting of `legend.title`.
 
 ```{r}
 #| fig.alt = "A scatter plot showing the highway miles per gallon on the x-axis
@@ -143,8 +143,8 @@ ggplot(mpg, aes(x = hwy, y = cty, color = drv)) +
  theme(
  legend.key.size = unit(1.5, "cm"),
  legend.key = element_rect(color = NA, fill = NA),
- legend.title.align = 0.5
-  )
+ legend.title = element_text(hjust = 0.5)
+ )
 ```
 
 </details>