Colourbar transparency

NEWS.md

@@ -1,5 +1,8 @@
 # ggplot2 (development version)
 
+* `guide_colourbar()` and `guide_coloursteps()` gain an `alpha` argument to
+  set the transparency of the bar (#5085).
+
 * Lines where `linewidth = NA` are now dropped in `geom_sf()` (#5204).
 
 * New `guide_axis_logticks()` can be used to draw logarithmic tick marks as

R/guide-colorbar.R

@@ -37,6 +37,9 @@ NULL
 #'   raster object. If `FALSE` then the colourbar is rendered as a set of
 #'   rectangles. Note that not all graphics devices are capable of rendering
 #'   raster image.
+#' @param alpha A numeric between 0 and 1 setting the colour transparency of
+#'   the bar. Use `NA` to preserve the alpha encoded in the colour itself
+#'   (default).
 #' @param ticks A theme object for rendering tick marks at the colourbar.
 #'   Usually, the object of `element_line()` is expected (default). If
 #'   `element_blank()`, no tick marks are drawn. For backward compatibility,
@@ -135,6 +138,7 @@ guide_colourbar <- function(
   barheight = NULL,
   nbin = 300,
   raster = TRUE,
+  alpha = NA,
 
   # frame
   frame = element_blank(),
@@ -205,6 +209,8 @@ guide_colourbar <- function(
     ticks$linewidth <- ticks.linewidth %||% ticks$linewidth %||% (0.5 / .pt)
   }
 
+  check_number_decimal(alpha, min = 0, max = 1, allow_na = TRUE)
+
   # Trick to re-use this constructor in `guide_coloursteps()`.
   args  <- list2(...)
   super <- args$super %||% GuideColourbar
@@ -230,6 +236,7 @@ guide_colourbar <- function(
     keyheight = barheight,
     nbin = nbin,
     raster = raster,
+    alpha = alpha,
 
     # frame
     frame = frame,
@@ -283,6 +290,7 @@ GuideColourbar <- ggproto(
     keyheight = NULL,
     nbin = 300,
     raster = TRUE,
+    alpha = NA,
 
     draw_lim = c(TRUE, TRUE),
 
@@ -322,15 +330,15 @@ GuideColourbar <- ggproto(
     Guide$extract_key(scale, aesthetic, ...)
   },
 
-  extract_decor = function(scale, aesthetic, nbin = 300, reverse = FALSE, ...) {
+  extract_decor = function(scale, aesthetic, nbin = 300, reverse = FALSE, alpha = NA, ...) {
 
     limits <- scale$get_limits()
     bar <- seq(limits[1], limits[2], length.out = nbin)
     if (length(bar) == 0) {
       bar <- unique0(limits)
     }
     bar <- data_frame0(
-      colour = scale$map(bar),
+      colour = alpha(scale$map(bar), alpha),
       value  = bar,
       .size  = length(bar)
     )

R/guide-colorsteps.R

@@ -114,11 +114,11 @@ GuideColoursteps <- ggproto(
 
   extract_decor = function(scale, aesthetic, key,
                            reverse = FALSE, even.steps = TRUE,
-                           nbin = 100, ...) {
+                           nbin = 100, alpha = NA,...) {
     if (even.steps) {
       bin_at <- attr(key, "bin_at", TRUE)
       bar <- data_frame0(
-        colour = scale$map(bin_at),
+        colour = alpha(scale$map(bin_at), alpha),
         min    = seq_along(bin_at) - 1,
         max    = seq_along(bin_at),
         .size  = length(bin_at)
@@ -128,7 +128,7 @@ GuideColoursteps <- ggproto(
       n <- length(breaks)
       bin_at <- (breaks[-1] + breaks[-n]) / 2
       bar <- data_frame0(
-        colour = scale$map(bin_at),
+        colour = alpha(scale$map(bin_at), alpha),
         min    = head(breaks, -1),
         max    = tail(breaks, -1),
         .size  = length(bin_at)

tests/testthat/test-guides.R

@@ -828,15 +828,16 @@ test_that("colorbar can be styled", {
     p + scale_color_gradient(low = 'white', high = 'red')
   )
 
-  expect_doppelganger("white-to-red colorbar, long thick black ticks, green frame",
+  expect_doppelganger("white-to-red semitransparent colorbar, long thick black ticks, green frame",
     p + scale_color_gradient(
           low = 'white', high = 'red',
           guide = guide_colorbar(
             frame = element_rect(colour = "green"),
             frame.linewidth = 1.5 / .pt,
             ticks.colour = "black",
             ticks.linewidth = 2.5 / .pt,
-            ticks.length = unit(0.4, "npc")
+            ticks.length = unit(0.4, "npc"),
+            alpha = 0.75
             )
         )
     )
@@ -894,8 +895,8 @@ test_that("coloursteps guide can be styled correctly", {
   expect_doppelganger("guide_coloursteps can have bins relative to binsize",
     p + guides(colour = guide_coloursteps(even.steps = FALSE))
   )
-  expect_doppelganger("guide_bins can show ticks",
-    p + guides(colour = guide_coloursteps(ticks = TRUE))
+  expect_doppelganger("guide_bins can show ticks and transparancy",
+    p + guides(colour = guide_coloursteps(ticks = TRUE, alpha = 0.75))
   )
 })