feat: 'patternFill' returns a pattern fill object

* `patternFill()` wraps `patternGrob()` to return a
  `grid::pattern()` fill object

closes #70

NAMESPACE

@@ -40,6 +40,7 @@ export(names_placeholder)
 export(names_polygon_tiling)
 export(names_square)
 export(names_weave)
+export(patternFill)
 export(patternGrob)
 export(pattern_hex)
 export(pattern_square)

NEWS.md

@@ -1,6 +1,9 @@
 gridpattern v1.2.0 (development)
 ================================
 
+* `patternFill()` wraps `patternGrob()` to return a
+  `grid::pattern()` fill object (#70).
+
 * `update_alpha()` updates fill colour and/or pattern transparency.
 
   + It is a fork of `ggplot2::fill_alpha()` by @teunbrand.

R/grid-pattern-fill.R

@@ -0,0 +1,48 @@
+#' Create patterned fills by pattern name
+#'
+#' `patternFill()` returns [grid::pattern()] fill objects.
+#' It is a wrapper around [patternGrob()].
+#'
+#' @param ... Passed to [patternGrob()].
+#' @param x,y,width,height  The size of the [grid::pattern()] tile.
+#' @param default.units  The default [grid::unit()] unit to use for `x`, `y`, `width`, and `height`.
+#' @param just,hjust,vjust  The justification of the tile relative to its location.
+#' @param group A logical indicating whether the pattern is relative to the bounding box of the grob or whether it is relative to individual shapes within the grob.  Ignored if R is less than version 4.2.
+#' @examples
+#' if (guess_has_R4.1_features("patterns") && require("grid")) {
+#'   grid.newpage()
+#'   stripe_fill <- patternFill("stripe", fill = c("red", "blue"))
+#'   grid.circle(gp = gpar(fill = stripe_fill))
+#' }
+#'  
+#' if (guess_has_R4.1_features("patterns") && 
+#'     require("ggplot2") && 
+#'     (getRversion() >= "4.2")) {
+#'   grid.newpage()
+#'   weave_fill <- patternFill("weave", fill = "red", fill2 = "blue", 
+#'                             colour = "transparent")
+#'   hex_fill <- patternFill("polygon_tiling", type = "hexagonal", 
+#'                           fill = c("black", "white", "grey"),
+#'                           colour = "transparent")
+#'   df <- data.frame(trt = c("a", "b"), outcome = c(1.9, 3.2))
+#'   gg <- ggplot(df, aes(trt, outcome)) +
+#'     geom_col(fill = list(weave_fill, hex_fill))
+#'   plot(gg)
+#' }
+#' @return A [grid::pattern()] fill object.
+#' @export
+patternFill <- function(..., 
+                        x = 0.5, y = 0.5, width = 1, height = 1,
+                        default.units = "npc",
+                        just = "centre", hjust = NULL, vjust = NULL,
+                        group = TRUE) {
+    stopifnot(getRversion() >= "4.1.0")
+    args <- list(grob = patternGrob(...),
+                 x = x, y = y, width = width, height = height, 
+                 default.units = default.units,
+                 just = just, hjust = hjust, vjust = vjust)
+    # `group` was introduced in R 4.2
+    if (getRversion() >= "4.2.0")
+        args$group <- group
+    do.call(grid::pattern, args)
+}

_pkgdown.yml

@@ -3,8 +3,12 @@ url: "https://trevorldavis.com/R/gridpattern"
 development:
     mode: auto
 reference:
-    - title: "Patterned grobs"
-      desc: "Patterned grob functions"
+    - title: "Pattern fills"
+      desc: "Pattern fill function"
+      contents:
+        - patternFill
+    - title: "Pattern grobs"
+      desc: "Pattern grob functions"
       contents:
         - starts_with("grid.pattern")
     - title: "Pattern matrices"