Refactor guide styling

NEWS.md

@@ -7,6 +7,24 @@
   `legend.title.position`. Previous style arguments in the `guide_*()` functions 
   have been soft-deprecated.
 
+* `draw_key_label()` now better reflects the appearance of labels.
+
+* The `minor_breaks` function argument in scales can now take a function with
+  two arguments: the scale's limits and the scale's major breaks (#3583).
+
+* (internal) The `ScaleContinuous$get_breaks()` method no longer censors
+  the computed breaks.
+
+* Plot scales now ignore `AsIs` objects constructed with `I(x)`, instead of
+  invoking the identity scale. This allows these columns to co-exist with other
+  layers that need a non-identity scale for the same aesthetic. Also, it makes
+  it easy to specify relative positions (@teunbrand, #5142).
+
+* The `fill` aesthetic in many geoms now accepts grid's patterns and gradients.
+  For developers of layer extensions, this feature can be enabled by switching 
+  from `fill = alpha(fill, alpha)` to `fill = fill_alpha(fill, alpha)` when 
+  providing fills to `grid::gpar()` (@teunbrand, #3997).
+
 * The plot's title, subtitle and caption now obey horizontal text margins
   (#5533).
 

R/guide-.R

@@ -300,8 +300,7 @@ Guide <- ggproto(
     key <- params$key
 
     # Setup parameters and theme
-    params$position  <- params$position  %||% position
-    params$direction <- params$direction %||% direction
+    params <- replace_null(params, position = position, direction = direction)
     params <- self$setup_params(params)
     elems  <- self$setup_elements(params, self$elements, theme)
     elems  <- self$override_elements(params, elems, theme)

R/guide-bins.R

@@ -42,14 +42,16 @@ NULL
 #' p
 #'
 #' # Remove the axis or style it
-#' p + guides(size = guide_bins(theme = theme(legend.axis = element_blank())))
+#' p + guides(size = guide_bins(
+#'   theme = theme(legend.axis.line = element_blank())
+#' ))
 #'
 #' p + guides(size = guide_bins(show.limits = TRUE))
 #'
 #' my_arrow <- arrow(length = unit(1.5, "mm"), ends = "both")
-#' p + guides(size = guide_bins(theme = theme(
-#'   legend.axis = element_line(arrow = my_arrow)
-#' )))
+#' p + guides(size = guide_bins(
+#'   theme = theme(legend.axis.line = element_line(arrow = my_arrow))
+#' ))
 #'
 #' # Guides are merged together if possible
 #' ggplot(mtcars) +
@@ -73,6 +75,9 @@ guide_bins <- function(
 ) {
 
   theme <- deprecated_guide_args(theme, ...)
+  if (!is.null(position)) {
+    position <- arg_match0(position, c(.trbl, "inside"))
+  }
 
   new_guide(
     # title

R/guide-colorbar.R

@@ -109,6 +109,7 @@ guide_colourbar <- function(
   raster = TRUE,
   draw.ulim = TRUE,
   draw.llim = TRUE,
+  position = NULL,
   direction = NULL,
   reverse = FALSE,
   order = 0,
@@ -117,13 +118,17 @@ guide_colourbar <- function(
 ) {
 
   theme <- deprecated_guide_args(theme, ...)
+  if (!is.null(position)) {
+    position <- arg_match0(position, c(.trbl, "inside"))
+  }
 
   new_guide(
     title = title,
     theme = theme,
     nbin = nbin,
     raster = raster,
     draw_lim = c(isTRUE(draw.llim), isTRUE(draw.ulim)),
+    position = position,
     direction = direction,
     reverse = reverse,
     order = order,

R/guide-legend.R

@@ -16,6 +16,8 @@
 #' @param theme A [`theme`][theme()] object to style the guide individually or
 #'   differently from the plot's theme settings. The `theme` argument in the
 #'   guide override,s and is combined with, the plot's theme.
+#' @param position A character string indicating where the legend should be
+#'   placed relative to the plot panels.
 #' @param direction  A character string indicating the direction of the guide.
 #'   One of "horizontal" or "vertical."
 #' @param override.aes A list specifying aesthetic parameters of legend key.
@@ -111,6 +113,10 @@ guide_legend <- function(
 
   theme <- deprecated_guide_args(theme, ...)
 
+  if (!is.null(position)) {
+    position <- arg_match0(position, c(.trbl, "inside"))
+  }
+
   new_guide(
     # Title
     title = title,

R/theme-elements.R

@@ -511,9 +511,11 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
   legend.text.position = el_def("character"),
   legend.title        = el_def("element_text", "title"),
   legend.title.position = el_def("character"),
-  legend.position     = el_def(c("character", "numeric", "integer")),
-  legend.direction    = el_def("character"),
   legend.byrow        = el_def("logical"),
+  legend.position     = el_def("character"),
+  legend.position.inside = el_def(c("numeric", "integer")),
+  legend.direction    = el_def("character"),
+
   legend.justification = el_def(c("character", "numeric", "integer")),
   legend.justification.top = el_def(
     c("character", "numeric", "integer"),

R/theme.R

@@ -91,8 +91,10 @@
 #'   `title`)
 #' @param legend.title.position placement of legend title relative to the main
 #'   legend ("top", "right", "bottom" or "left").
-#' @param legend.position the position of legends ("none", "left", "right",
-#'   "bottom", "top", or two-element numeric vector)
+#' @param legend.position the default position of legends ("none", "left",
+#'   "right", "bottom", "top", "inside")
+#' @param legend.position.inside A numeric vector of length two setting the
+#'   placement of legends that have the `"inside"` position.
 #' @param legend.direction layout of items in legends ("horizontal" or
 #'   "vertical")
 #' @param legend.byrow whether the legend-matrix is filled by columns

R/utilities.R

@@ -773,9 +773,17 @@ vec_rbind0 <- function(..., .error_call = current_env(), .call = caller_env()) {
   )
 }
 
+# This function is used to vectorise the following pattern:
+#
+# list$name1 <- list$name1 %||% value
+# list$name2 <- list$name2 %||% value
+#
+# and express this pattern as:
+#
+# replace_null(list, name1 = value, name2 = value)
 replace_null <- function(list, ..., env = caller_env()) {
   # Collect dots without evaluating
-  dots <- match.call(replace_null, expand.dots = FALSE)$`...`
+  dots <- enexprs(...)
   # Select arguments that are null in `list`
   nms  <- names(dots)
   nms  <- nms[vapply(list[nms], is.null, logical(1))]