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

Author: teunbrand

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).
 

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, ...) {

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

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",

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")),

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) {

man/theme.Rd

@@ -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>