feat: 'pattern_fill2' accept pattern/gradient fills

* `pattern_fill2` now also accepts pattern/gradient fills
  (which is supported by "crosshatch" and "weave" patterns)
* Move geom roxygen code into `R/a-geom-docs.R`
* Wherever documents `pattern_fill` and `pattern_fill2` tweak
  wording to note supports grid pattern/gradient fills in addition
  to colours

.Rbuildignore

@@ -14,5 +14,6 @@
 ^doc$
 ^Meta$
 ^revdep$
+^tmp$
 vignettes/precompute_vignettes.R
 vignettes/*.Rmd.orig

.Rbuildignore_CRAN

@@ -14,6 +14,7 @@
 ^doc$
 ^Meta$
 ^revdep$
+^tmp$
 vignettes/precompute_vignettes.R
 vignettes/*.Rmd.orig
 

.gitignore

@@ -14,3 +14,4 @@ pkgdown
 /doc/
 /Meta/
 /revdep/
+/tmp/

DESCRIPTION

@@ -42,6 +42,7 @@ Suggests:
     vdiffr (>= 1.0.6)
 VignetteBuilder: knitr, ragg, rmarkdown
 Collate: 
+    'a-geom-docs.R'
     'aaa-ggplot2-compat-plyr.R'
     'aaa-ggplot2-ggplot-global.R'
     'aaa-ggplot2-performance.R'

NEWS.md

@@ -35,10 +35,11 @@
 * Each pattern aesthetic may now be a list of vectors with each list element
   providing that aesthetic for a different pattern (#100).
   Most builtin `{gridpattern}` "geometry" patterns support multiple fill colors etc. which previously we could only access in `{ggpattern}` via custom patterns.
-* The `fill` and `pattern_fill` aesthetics may now be (a list of) gradient/pattern fills
+* The `fill`, `pattern_fill`, and `pattern_fill2` aesthetics may now be (a list of) gradient/pattern fills
   (in addition to color strings) (#112).
-  Note using gradient/pattern fills will require R (>= 4.2) and a graphics device with support for the gradient/pattern fill feature.
-  Use of just color fills should continue to work on a wider variety of R versions and graphics devices.
+  Note using gradient/pattern fills will require R (>= 4.2), a graphics device with support for the gradient/pattern fill feature,
+  and will work only for a subset of patterns (i.e. most of the "geometry" patterns).
+  Use of just color fills should continue to work on a wider variety of R versions, graphics devices, and patterns.
 * {ggpattern} now supports the `pattern_units` aesthetic (#81).
   Supported by most "geometry" patterns.
   It sets the `grid::unit()` used by the `pattern_spacing`, `pattern_xoffset`, `pattern_yoffset`,

R/a-geom-docs.R

@@ -0,0 +1,113 @@
+#' ggplot2 geoms with support for pattern fills
+#'
+#' All geoms in this package are identical to their counterparts in ggplot2 except
+#' that they can be filled with patterns.
+#'
+#' @section Pattern Arguments:
+#'
+#' Not all arguments apply to all patterns.
+#'
+#' \describe{
+#' \item{\strong{`pattern`}}{Pattern name string e.g. 'stripe' (default), 'crosshatch', 'point', 'circle', 'none'}
+#' \item{\strong{`pattern_alpha`}}{ Alpha transparency for pattern. default: 1}
+#' \item{\strong{`pattern_angle`}}{ Orientation of the pattern in degrees. default: 30}
+#' \item{\strong{`pattern_aspect_ratio`}}{ Aspect ratio adjustment. }
+#' \item{\strong{`pattern_colour`}}{ Colour used for strokes and points. default: 'black'}
+#' \item{\strong{`pattern_density`}}{ Approximate fill fraction of the pattern. Usually in range \[0, 1], but can be higher. default: 0.2}
+#' \item{\strong{`pattern_filename`}}{ Image filename/URL. }
+#' \item{\strong{`pattern_fill`}}{ Fill colour (or [grid::pattern()]/gradient fill). default: 'grey80'}
+#' \item{\strong{`pattern_fill2`}}{ Second fill colour (or [grid::pattern()]/gradient fill). default: '#4169E1'}
+#' \item{\strong{`pattern_filter`}}{ (Image scaling) filter. default: 'lanczos' }
+#' \item{\strong{`pattern_frequency`}}{ Frequency. default: 0.1 }
+#' \item{\strong{`pattern_gravity`}}{ Image placement. default: 'center' }
+#' \item{\strong{`pattern_grid`}}{ Pattern grid type. default: 'square' }
+#' \item{\strong{`pattern_key_scale_factor`}}{ Scale factor for pattern in legend. default: 1 }
+#' \item{\strong{`pattern_linetype`}}{ Stroke linetype. default: 1}
+#' \item{\strong{`pattern_option_1`}}{ Generic user value for custom patterns. }
+#' \item{\strong{`pattern_option_2`}}{ Generic user value for custom patterns. }
+#' \item{\strong{`pattern_option_3`}}{ Generic user value for custom patterns. }
+#' \item{\strong{`pattern_option_4`}}{ Generic user value for custom patterns. }
+#' \item{\strong{`pattern_option_5`}}{ Generic user value for custom patterns. }
+#' \item{\strong{`pattern_orientation`}}{ 'vertical', 'horizontal', or 'radial'. default: 'vertical' }
+#' \item{\strong{`pattern_res`}}{ Pattern resolution (pixels per inch). }
+#' \item{\strong{`pattern_rot`}}{ Rotation angle (shape within pattern). default: 0 }
+#' \item{\strong{`pattern_scale`}}{ Scale. default: 1}
+#' \item{\strong{`pattern_shape`}}{ Plotting shape. default: 1}
+#' \item{\strong{`pattern_size`}}{ Stroke line width. default: 1}
+#' \item{\strong{`pattern_spacing`}}{ Spacing of the pattern as a fraction of the plot size. default: 0.05}
+#' \item{\strong{`pattern_type`}}{ Generic control option }
+#' \item{\strong{`pattern_subtype`}}{ Generic control option }
+#' \item{\strong{`pattern_xoffset`}}{Offset the origin of the pattern. Range \[0, 1]. default: 0.  Use this to slightly shift the origin of the pattern. For most patterns, the user should limit the offset value to be less than the pattern spacing.}
+#' \item{\strong{`pattern_yoffset`}}{Offset the origin of the pattern. Range \[0, 1]. default: 0.  Use this to slightly shift the origin of the pattern. For most patterns, the user should limit the offset value to be less than the pattern spacing.}
+#' }
+#' @inheritParams ggplot2::geom_bar
+#' @inheritParams ggplot2::geom_boxplot
+#' @inheritParams ggplot2::geom_crossbar
+#' @inheritParams ggplot2::geom_histogram
+#' @inheritParams ggplot2::geom_map
+#' @inheritParams ggplot2::geom_polygon
+#' @inheritParams ggplot2::geom_rect
+#' @inheritParams ggplot2::geom_ribbon
+#' @inheritParams ggplot2::geom_violin
+#' @examples
+#'   if (require("ggplot2")) {
+#'
+#'     # 'stripe' pattern example
+#'     df <- data.frame(level = c("a", "b", "c", 'd'), outcome = c(2.3, 1.9, 3.2, 1))
+#'     gg <- ggplot(df) +
+#'       geom_col_pattern(
+#'         aes(level, outcome, pattern_fill = level),
+#'         pattern = 'stripe',
+#'         fill    = 'white',
+#'         colour  = 'black'
+#'       ) +
+#'       theme_bw(18) +
+#'       theme(legend.position = 'none') +
+#'       labs(
+#'         title    = "ggpattern::geom_col_pattern()",
+#'         subtitle = "pattern = 'stripe'"
+#'       )
+#'     plot(gg)
+#'
+#'     # 'pch' pattern example
+#'     gg <- ggplot(mtcars, aes(as.factor(cyl), mpg)) +
+#'       geom_violin_pattern(aes(fill = as.factor(cyl),
+#'                               pattern_shape = as.factor(cyl)),
+#'         pattern = 'pch',
+#'         pattern_density = 0.3,
+#'         pattern_angle = 0,
+#'         colour  = 'black'
+#'       ) +
+#'       theme_bw(18) +
+#'       theme(legend.position = 'none') +
+#'       labs(
+#'         title    = "ggpattern::geom_violin_pattern()",
+#'         subtitle = "pattern = 'pch'"
+#'       )
+#'     plot(gg)
+#'
+#'     # 'polygon_tiling' pattern example
+#'     gg <- ggplot(mtcars) +
+#'        geom_density_pattern(
+#'          aes(
+#'            x            = mpg,
+#'            pattern_fill = as.factor(cyl),
+#'            pattern_type = as.factor(cyl)
+#'          ),
+#'          pattern = 'polygon_tiling',
+#'          pattern_key_scale_factor = 1.2
+#'        ) +
+#'        scale_pattern_type_manual(values = c("hexagonal", "rhombille",
+#'                                   "pythagorean")) +
+#'        theme_bw(18) +
+#'        theme(legend.key.size = unit(2, 'cm')) +
+#'        labs(
+#'          title    = "ggpattern::geom_density_pattern()",
+#'          subtitle = "pattern = 'polygon_tiling'"
+#'        )
+#'     plot(gg)
+#'   }
+#'
+#' @return A [ggplot2::Geom] object.
+#' @name geom-docs
+NULL

R/geom-bar.R

@@ -1,119 +1,5 @@
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#' ggplot2 geoms with support for pattern fills
-#'
-#' All geoms in this package are identical to their counterparts in ggplot2 except
-#' that they can be filled with patterns.
-#'
-#' @section Pattern Arguments:
-#'
-#' Not all arguments apply to all patterns.
-#'
-#' \describe{
-#' \item{\strong{`pattern`}}{Pattern name string e.g. 'stripe' (default), 'crosshatch', 'point', 'circle', 'none'}
-#' \item{\strong{`pattern_alpha`}}{ Alpha transparency for pattern. default: 1}
-#' \item{\strong{`pattern_angle`}}{ Orientation of the pattern in degrees. default: 30}
-#' \item{\strong{`pattern_aspect_ratio`}}{ Aspect ratio adjustment. }
-#' \item{\strong{`pattern_colour`}}{ Colour used for strokes and points. default: 'black'}
-#' \item{\strong{`pattern_density`}}{ Approximate fill fraction of the pattern. Usually in range \[0, 1], but can be higher. default: 0.2}
-#' \item{\strong{`pattern_filename`}}{ Image filename/URL. }
-#' \item{\strong{`pattern_fill`}}{ Fill colour. default: 'grey80'}
-#' \item{\strong{`pattern_fill2`}}{ Second fill colour. default: '#4169E1'}
-#' \item{\strong{`pattern_filter`}}{ (Image scaling) filter. default: 'lanczos' }
-#' \item{\strong{`pattern_frequency`}}{ Frequency. default: 0.1 }
-#' \item{\strong{`pattern_gravity`}}{ Image placement. default: 'center' }
-#' \item{\strong{`pattern_grid`}}{ Pattern grid type. default: 'square' }
-#' \item{\strong{`pattern_key_scale_factor`}}{ Scale factor for pattern in legend. default: 1 }
-#' \item{\strong{`pattern_linetype`}}{ Stroke linetype. default: 1}
-#' \item{\strong{`pattern_option_1`}}{ Generic user value for custom patterns. }
-#' \item{\strong{`pattern_option_2`}}{ Generic user value for custom patterns. }
-#' \item{\strong{`pattern_option_3`}}{ Generic user value for custom patterns. }
-#' \item{\strong{`pattern_option_4`}}{ Generic user value for custom patterns. }
-#' \item{\strong{`pattern_option_5`}}{ Generic user value for custom patterns. }
-#' \item{\strong{`pattern_orientation`}}{ 'vertical', 'horizontal', or 'radial'. default: 'vertical' }
-#' \item{\strong{`pattern_res`}}{ Pattern resolution (pixels per inch). }
-#' \item{\strong{`pattern_rot`}}{ Rotation angle (shape within pattern). default: 0 }
-#' \item{\strong{`pattern_scale`}}{ Scale. default: 1}
-#' \item{\strong{`pattern_shape`}}{ Plotting shape. default: 1}
-#' \item{\strong{`pattern_size`}}{ Stroke line width. default: 1}
-#' \item{\strong{`pattern_spacing`}}{ Spacing of the pattern as a fraction of the plot size. default: 0.05}
-#' \item{\strong{`pattern_type`}}{ Generic control option }
-#' \item{\strong{`pattern_subtype`}}{ Generic control option }
-#' \item{\strong{`pattern_xoffset`}}{Offset the origin of the pattern. Range \[0, 1]. default: 0.  Use this to slightly shift the origin of the pattern. For most patterns, the user should limit the offset value to be less than the pattern spacing.}
-#' \item{\strong{`pattern_yoffset`}}{Offset the origin of the pattern. Range \[0, 1]. default: 0.  Use this to slightly shift the origin of the pattern. For most patterns, the user should limit the offset value to be less than the pattern spacing.}
-#' }
-#'
-#' @inheritParams ggplot2::geom_bar
-#' @inheritParams ggplot2::geom_boxplot
-#' @inheritParams ggplot2::geom_crossbar
-#' @inheritParams ggplot2::geom_histogram
-#' @inheritParams ggplot2::geom_map
-#' @inheritParams ggplot2::geom_polygon
-#' @inheritParams ggplot2::geom_rect
-#' @inheritParams ggplot2::geom_ribbon
-#' @inheritParams ggplot2::geom_violin
 #' @rdname geom-docs
-#' @examples
-#'   if (require("ggplot2")) {
-#'
-#'     # 'stripe' pattern example
-#'     df <- data.frame(level = c("a", "b", "c", 'd'), outcome = c(2.3, 1.9, 3.2, 1))
-#'     gg <- ggplot(df) +
-#'       geom_col_pattern(
-#'         aes(level, outcome, pattern_fill = level),
-#'         pattern = 'stripe',
-#'         fill    = 'white',
-#'         colour  = 'black'
-#'       ) +
-#'       theme_bw(18) +
-#'       theme(legend.position = 'none') +
-#'       labs(
-#'         title    = "ggpattern::geom_col_pattern()",
-#'         subtitle = "pattern = 'stripe'"
-#'       )
-#'     plot(gg)
-#'
-#'     # 'pch' pattern example
-#'     gg <- ggplot(mtcars, aes(as.factor(cyl), mpg)) +
-#'       geom_violin_pattern(aes(fill = as.factor(cyl),
-#'                               pattern_shape = as.factor(cyl)),
-#'         pattern = 'pch',
-#'         pattern_density = 0.3,
-#'         pattern_angle = 0,
-#'         colour  = 'black'
-#'       ) +
-#'       theme_bw(18) +
-#'       theme(legend.position = 'none') +
-#'       labs(
-#'         title    = "ggpattern::geom_violin_pattern()",
-#'         subtitle = "pattern = 'pch'"
-#'       )
-#'     plot(gg)
-#'
-#'     # 'polygon_tiling' pattern example
-#'     gg <- ggplot(mtcars) +
-#'        geom_density_pattern(
-#'          aes(
-#'            x            = mpg,
-#'            pattern_fill = as.factor(cyl),
-#'            pattern_type = as.factor(cyl)
-#'          ),
-#'          pattern = 'polygon_tiling',
-#'          pattern_key_scale_factor = 1.2
-#'        ) +
-#'        scale_pattern_type_manual(values = c("hexagonal", "rhombille",
-#'                                   "pythagorean")) +
-#'        theme_bw(18) +
-#'        theme(legend.key.size = unit(2, 'cm')) +
-#'        labs(
-#'          title    = "ggpattern::geom_density_pattern()",
-#'          subtitle = "pattern = 'polygon_tiling'"
-#'        )
-#'     plot(gg)
-#'   }
-#'
-#' @return A [ggplot2::Geom] object.
 #' @export
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 geom_bar_pattern <- function(mapping = NULL, data = NULL,
                              stat = "count", position = "stack",
                              ...,

R/geom-bin2d.R

@@ -22,6 +22,6 @@ geom_bin_2d_pattern <- function(mapping = NULL, data = NULL,
   )
 }
 
-#' @export
 #' @rdname geom-docs
+#' @export
 geom_bin2d_pattern <- geom_bin_2d_pattern

R/pattern.R

@@ -14,7 +14,7 @@ munge_params <- function(params) {
     l <- as.list(params)
     nms <- grep("^pattern_", names(l), value = TRUE)
     # must avoid unlisting `grid::pattern()` fill values
-    nms <- grep("^pattern_fill$", nms, invert = TRUE, value = TRUE)
+    nms <- grep("^pattern_fill", nms, invert = TRUE, value = TRUE)
     for (nm in nms) {
         l[[nm]] <- unlist(l[[nm]])
     }

vignettes/developing-patterns.Rmd

@@ -74,8 +74,8 @@ so may make your pattern more useful for others:
 | `pattern_colour`           | Stroke colour                                 | 'grey20'   | colour                             |
 | `pattern_density`          | Approx. fraction of area the pattern fills    | 0.2        | value in range [0, 1]              |
 | `pattern_filename`         | Image filename/URL                            | ''         | Filename/URL                       |
-| `pattern_fill2`            | Second fill colour                            | '#4169E1'  | colour                             |
-| `pattern_fill`             | Fill colour                                   | 'grey80'   | colour                             |
+| `pattern_fill`             | Fill colour                                   | 'grey80'   | colour (or grid pattern/gradient)  |
+| `pattern_fill2`            | Second fill colour                            | '#4169E1'  | colour (or grid pattern/gradient)  |
 | `pattern_filter`           | Image scaling filter                          | 'lanczos'  | `magick::filter_types`             |
 | `pattern_frequency`        | Frequency                                     | 0.1        |                                    |
 | `pattern_gravity`          | Image placement                               | 'center'   | `magick::gravity_types`            |
@@ -244,4 +244,4 @@ ggplot(df, aes(trt, outcome)) +
 
 The `{gridpattern}` package contains a vignette on developing `{gridpattern}` / `{ggpattern}` patterns with a few more examples including an example of layering patterns on top of each other.  Use [`vignette("developing-patterns", package="gridpattern")`](https://trevorldavis.com/R/gridpattern/dev/articles/developing-patterns.html) to see it.
 
-Also the `{gridpattern}` source contains the full source code for seventeen patterns: https://github.com/trevorld/gridpattern/tree/main/R
+Also the `{gridpattern}` source contains the full source code for  `r length(gridpattern::names_pattern)`patterns: https://github.com/trevorld/gridpattern/tree/main/R

vignettes/patterns-tilings.Rmd

@@ -46,7 +46,7 @@ those pixel patterns to fill the geom.
 | Aesthetic                  | Description                        | Default   |
 |----------------------------|------------------------------------|-----------|
 | `pattern_type`             | Image scaling type                 | 'fit'     |
-| `pattern_fill`             | Colour                             | 'grey20'  |
+| `pattern_fill`             | Colour (or grid pattern/gradient)  | 'grey20'  |
 | `pattern_scale`            | Extra scaling                      | 1         |
 | `pattern_filter`           | Filter to use when scaling         | 'box    ' |
 | `pattern_alpha`            | Alpha                              | NA        |