docs: Improve examples as rendered in {pkgdown}

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: gridpattern
 Type: Package
 Title: 'grid' Pattern Grobs
-Version: 1.2.0-2
+Version: 1.2.0-3
 Authors@R: c(person("Mike", "FC", role = "aut", comment = "Code/docs adapted from ggpattern"),
         person("Trevor L.", "Davis", role=c("aut", "cre"), email="[email protected]",
                comment = c(ORCID = "0000-0001-6341-4639")),

R/alphaMaskGrob.R

@@ -33,9 +33,9 @@
 #'                              id = rep(1:2, each = 7),
 #'                              rule = "evenodd", gp = gp)
 #'     masked <- alphaMaskGrob(maskee, masker, use_R4.1_masks = FALSE)
-#'     grid.newpage()
 #'     grid.draw(masked)
-#'
+#'   }
+#'   if (capabilities("png") && require("grid")) {
 #'     maskee_transparent <- rectGrob(gp = gpar(col = NA, fill = "blue"))
 #'     gp <- gpar(lwd = 20, col = "black", fill = grDevices::rgb(0, 0, 0, 0.5))
 #'     masker_transparent <- editGrob(masker, gp = gp)

R/grid-pattern.R

@@ -62,51 +62,51 @@
 #' @examples
 #'  print(names_pattern)
 #'  \donttest{ # Once took more >10s on a CRAN autocheck
-#'  if (require("grid")) {
-#'    x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
-#'    y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
+#'  x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
+#'  y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
 #'
-#'    # geometry-based patterns
-#'    # 'stripe' pattern
-#'    grid.newpage()
-#'    grid.pattern("stripe", x_hex, y_hex,
-#'                 colour="black", fill=c("yellow", "blue"), density = 0.5)
+#'  # geometry-based patterns
+#'  # 'stripe' pattern
+#'  grid::grid.newpage()
+#'  grid.pattern("stripe", x_hex, y_hex,
+#'               colour="black", fill=c("yellow", "blue"), density = 0.5)
 #'
-#'    # Can alternatively use "gpar()" to specify colour and line attributes
-#'    grid.newpage()
-#'    grid.pattern("stripe", x_hex, y_hex, gp = gpar(col="blue", fill="red", lwd=2))
+#'  # Can alternatively use "gpar()" to specify colour and line attributes
+#'  grid::grid.newpage()
+#'  grid.pattern("stripe", x_hex, y_hex, 
+#'               gp = grid::gpar(col="blue", fill="red", lwd=2))
 #'
-#'    # 'weave' pattern
-#'    grid.newpage()
-#'    grid.pattern("weave", x_hex, y_hex, type = "satin",
-#'                 colour = "black", fill = "lightblue", fill2 =  "yellow",
-#'                 density = 0.3)
+#'  # 'weave' pattern
+#'  grid::grid.newpage()
+#'  grid.pattern("weave", x_hex, y_hex, type = "satin",
+#'               colour = "black", fill = "lightblue", fill2 =  "yellow",
+#'               density = 0.3)
 #'
-#'    # 'regular_polygon' pattern
-#'    grid.newpage()
-#'    grid.pattern_regular_polygon(x_hex, y_hex, colour = "black",
-#'                                 fill = c("blue", "yellow", "red"),
-#'                                 shape = c("convex4", "star8", "circle"),
-#'                                 density = c(0.45, 0.42, 0.4),
-#'                                 spacing = 0.08, angle = 0)
+#'  # 'regular_polygon' pattern
+#'  grid::grid.newpage()
+#'  grid.pattern_regular_polygon(x_hex, y_hex, colour = "black",
+#'                               fill = c("blue", "yellow", "red"),
+#'                               shape = c("convex4", "star8", "circle"),
+#'                               density = c(0.45, 0.42, 0.4),
+#'                               spacing = 0.08, angle = 0)
 #'
-#'    # can be used to achieve a variety of 'tiling' effects
-#'    grid.newpage()
-#'    grid.pattern_regular_polygon(x_hex, y_hex, color = "transparent",
-#'                                 fill = c("white", "grey", "black"),
-#'                                 density = 1.0, spacing = 0.1,
-#'                                 shape = "convex6", grid = "hex")
-#'    if (require("magick")) {
-#'      # array-based patterns
-#'      # 'image' pattern
-#'      logo_filename <- system.file("img", "Rlogo.png" , package="png")
-#'      grid.newpage()
-#'      grid.pattern("image", x_hex, y_hex, filename=logo_filename, type="fit")
-#'
-#'      # 'plasma' pattern
-#'      grid.newpage()
-#'      grid.pattern("plasma", x_hex, y_hex, fill="green")
-#'    }
+#'  # can be used to achieve a variety of 'tiling' effects
+#'  grid::grid.newpage()
+#'  grid.pattern_regular_polygon(x_hex, y_hex, color = "transparent",
+#'                               fill = c("white", "grey", "black"),
+#'                               density = 1.0, spacing = 0.1,
+#'                               shape = "convex6", grid = "hex")
+#'  if (suppressPackageStartupMessages(requireNamespace("magick", quietly = TRUE))) {
+#'    # array-based patterns
+#'    # 'image' pattern
+#'    logo_filename <- system.file("img", "Rlogo.png" , package="png")
+#'    grid::grid.newpage()
+#'    grid.pattern("image", x_hex, y_hex, filename=logo_filename, type="fit")
+#'  }
+#'  if (suppressPackageStartupMessages(requireNamespace("magick", quietly = TRUE))) {
+#'    # 'plasma' pattern
+#'    grid::grid.newpage()
+#'    grid.pattern("plasma", x_hex, y_hex, fill="green")
 #'  }
 #'  }
 #' @seealso \url{https://coolbutuseless.github.io/package/ggpattern/index.html}

R/pattern-array-ambient.R

@@ -8,10 +8,12 @@
 #' @inheritParams ambient::noise_worley
 #' @return A grid grob object invisibly.  If `draw` is `TRUE` then also draws to the graphic device as a side effect.
 #' @examples
-#'  if (requireNamespace("ambient")) {
+#'  if (requireNamespace("ambient", quietly = TRUE)) {
 #'    x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
 #'    y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
 #'    grid.pattern_ambient(x_hex, y_hex, fill = "green", fill2 = "blue")
+#'  }
+#'  if (requireNamespace("ambient")) {
 #'    grid::grid.newpage()
 #'    grid.pattern_ambient(x_hex, y_hex, fill = "green", fill2 = "blue", type = "cubic")
 #'  }

R/pattern-array-image.R

@@ -27,7 +27,8 @@
 #'     y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
 #'     logo_filename <- system.file("img", "Rlogo.png" , package = "png")
 #'     grid.pattern_image(x_hex, y_hex, filename = logo_filename, type = "fit")
-#'
+#'   }
+#'   if (requireNamespace("magick")) {
 #'     # "tile" `type` image pattern depends on `magick` functionality
 #'     # which is not reliable across platforms
 #'     grid::grid.newpage()

R/pattern-both-gradient.R

@@ -13,11 +13,13 @@
 #' @param res Assumed resolution (in pixels per graphic device inch) to use when creating array pattern.
 #' @return A grid grob object invisibly.  If `draw` is `TRUE` then also draws to the graphic device as a side effect.
 #' @examples
-#'  if (require("grid") && require("magick") && capabilities("png")) {
+#'  if (requireNamespace("magick") && capabilities("png")) {
 #'    x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
 #'    y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
 #'    grid.pattern_gradient(x_hex, y_hex, fill = "green")
-#'    grid.newpage()
+#'  }
+#'  if (requireNamespace("magick") && capabilities("png")) {
+#'    grid::grid.newpage()
 #'    grid.pattern_gradient(x_hex, y_hex, fill = "green", orientation = "radial")
 #'  }
 #' @export

R/pattern-both-rose.R

@@ -9,20 +9,22 @@
 #' @return A grid grob object invisibly.  If `draw` is `TRUE` then also draws to the graphic device as a side effect.
 #' @seealso See \url{https://en.wikipedia.org/wiki/Rose_(mathematics)} for more information.
 #' @examples
-#'   if (require("grid") && capabilities("png")) {
+#'   if (capabilities("png") || guess_has_R4.1_features("masks")) {
 #'     x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
 #'     y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
-#'     gp <- gpar(fill = c("blue", "red", "yellow", "green"), col = "black")
-#'
-#'     grid.newpage()
+#'     gp <- grid::gpar(fill = c("blue", "red", "yellow", "green"), col = "black")
 #'     grid.pattern_rose(x_hex, y_hex,
 #'                       spacing = 0.15, density = 0.5, angle = 0,
 #'                       frequency = 1:4, gp = gp)
-#'     grid.newpage()
+#'   }
+#'   if (capabilities("png") || guess_has_R4.1_features("masks")) {
+#'     grid::grid.newpage()
 #'     grid.pattern_rose(x_hex, y_hex,
 #'                       spacing = 0.15, density = 0.5, angle = 0,
 #'                       frequency = 1/1:4, gp = gp)
-#'     grid.newpage()
+#'   }
+#'   if (capabilities("png") || guess_has_R4.1_features("masks")) {
+#'     grid::grid.newpage()
 #'     grid.pattern_rose(x_hex, y_hex,
 #'                       spacing = 0.18, density = 0.5, angle = 0,
 #'                       frequency = c(3/2, 7/3, 5/4, 3/7), gp = gp)

R/pattern-both-text.R

@@ -11,14 +11,12 @@
 #' @param fontface The font face.  See [grid::gpar()] for more details.
 #' @return A grid grob object invisibly.  If `draw` is `TRUE` then also draws to the graphic device as a side effect.
 #' @examples
-#' if (require("grid") &&
-#'     capabilities("png") &&
+#' if (capabilities("png") &&
 #'     gridpattern:::device_supports_unicode()) {
 #'   x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
 #'   y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
 #'
 #'   playing_card_symbols <- c("\u2660", "\u2665", "\u2666", "\u2663")
-#'   grid.newpage()
 #'   grid.pattern_text(x_hex, y_hex,
 #'                    shape = playing_card_symbols,
 #'                    colour = c("black", "red", "red", "black"),

R/pattern-geometry-circle.R

@@ -28,21 +28,18 @@
 #'             more information about supported `subtype` arguments.
 #' @return A grid grob object invisibly.  If `draw` is `TRUE` then also draws to the graphic device as a side effect.
 #' @examples
-#'   if (require("grid")) {
-#'     x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
-#'     y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
-#'     grid.pattern_circle(x_hex, y_hex, fill = c("blue", "yellow"), density = 0.5)
-#'     grid.newpage()
-#'     grid.pattern_circle(x_hex, y_hex, density = 0.8, grid = "hex_circle",
-#'                         gp = gpar(fill = c("blue", "yellow", "red")))
-#'     grid.newpage()
-#'     grid.pattern_circle(x_hex, y_hex, density = 1.2, grid = "hex_circle",
-#'                         gp = gpar(fill = c("blue", "yellow", "red")))
-#'
-#'     # using a "twill_zigzag" 'weave' pattern
-#'     grid.newpage()
-#'     grid.pattern_circle(x_hex, y_hex, fill = "blue", density = 0.5, type = "twill_zigzag")
-#'   }
+#' x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
+#' y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
+#' grid.pattern_circle(x_hex, y_hex, fill = c("blue", "yellow"), density = 0.5)
+#' grid::grid.newpage()
+#' grid.pattern_circle(x_hex, y_hex, density = 0.8, grid = "hex_circle",
+#'                     gp = gpar(fill = c("blue", "yellow", "red")))
+#' grid::grid.newpage()
+#' grid.pattern_circle(x_hex, y_hex, density = 1.2, grid = "hex_circle",
+#'                     gp = gpar(fill = c("blue", "yellow", "red")))
+#' # using a "twill_zigzag" 'weave' pattern
+#' grid::grid.newpage()
+#' grid.pattern_circle(x_hex, y_hex, fill = "blue", density = 0.5, type = "twill_zigzag")
 #' @seealso
 #'   See [grid.pattern_regular_polygon()] for a more general case of this pattern.
 #' @export

R/pattern-geometry-crosshatch.R

@@ -6,15 +6,13 @@
 #' @param fill2 The fill colour for the \dQuote{top} crosshatch lines.
 #' @return A grid grob object invisibly.  If `draw` is `TRUE` then also draws to the graphic device as a side effect.
 #' @examples
-#'   if (require("grid")) {
-#'     x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
-#'     y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
-#'     grid.pattern_crosshatch(x_hex, y_hex, colour = "black", fill = "blue",
-#'                             fill2 = "yellow", density = 0.5)
-#'     grid.newpage()
-#'     grid.pattern_crosshatch(x_hex, y_hex, density = 0.3,
-#'                             gp = gpar(col = "blue", fill = "yellow"))
-#'   }
+#' x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
+#' y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
+#' grid.pattern_crosshatch(x_hex, y_hex, colour = "black", fill = "blue",
+#'                         fill2 = "yellow", density = 0.5)
+#' grid::grid.newpage()
+#' grid.pattern_crosshatch(x_hex, y_hex, density = 0.3,
+#'                         gp = gpar(col = "blue", fill = "yellow"))
 #' @seealso [grid.pattern_weave()] which interweaves two sets of lines.
 #'        For a single set of lines use [grid.pattern_stripe()].
 #' @export

R/pattern-geometry-pch.R

@@ -10,36 +10,40 @@
 #' @return A grid grob object invisibly.  If `draw` is `TRUE` then also draws to the graphic device as a side effect.
 #' @seealso [grid.pattern_regular_polygon()] which is used to implement this pattern.
 #' @examples
-#'   if (require("grid")) {
-#'     x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
-#'     y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
-#'     gp <- gpar(col = "black", fill = "lightblue")
+#' x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
+#' y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
+#' gp <- grid::gpar(col = "black", fill = "lightblue")
 #'
-#'     # pch 0-6 are simple shapes with no fill
-#'     grid.pattern_pch(x_hex, y_hex, shape = 0:6, gp = gp,
-#'                      spacing = 0.1, density = 0.4, angle = 0)
-#'
-#'     # pch 7-14 are compound shapes with no fill
-#'     grid.newpage()
-#'     grid.pattern_pch(x_hex, y_hex, shape = 7:14, gp = gp,
-#'                      spacing = 0.1, density = 0.4, angle = 0)
-#'
-#'     # pch 15-20 are filled with 'col'
-#'     grid.newpage()
-#'     grid.pattern_pch(x_hex, y_hex, shape = 15:20, gp = gp,
-#'                      spacing = 0.1, density = 0.4, angle = 0)
-#'
-#'     # pch 21-25 are filled with 'fill'
-#'     grid.newpage()
-#'     grid.pattern_pch(x_hex, y_hex, shape = 21:25, gp = gp,
-#'                      spacing = 0.1, density = 0.4, angle = 0)
-#'
-#'     # using a 'basket' weave `type` with two shapes
-#'     grid.newpage()
-#'     grid.pattern_pch(x_hex, y_hex, shape = c(1,4), gp = gp,
-#'                      type = "basket",
-#'                      spacing = 0.1, density = 0.4, angle = 0)
-#'   }
+#' if (capabilities("png") || guess_has_R4.1_features("masks")) {
+#'   # pch 0-6 are simple shapes with no fill
+#'   grid.pattern_pch(x_hex, y_hex, shape = 0:6, gp = gp,
+#'                    spacing = 0.1, density = 0.4, angle = 0)
+#' }
+#' if (capabilities("png") || guess_has_R4.1_features("masks")) {
+#'   # pch 7-14 are compound shapes with no fill
+#'   grid::grid.newpage()
+#'   grid.pattern_pch(x_hex, y_hex, shape = 7:14, gp = gp,
+#'                    spacing = 0.1, density = 0.4, angle = 0)
+#' }
+#' if (capabilities("png") || guess_has_R4.1_features("masks")) {
+#'   # pch 15-20 are filled with 'col'
+#'   grid::grid.newpage()
+#'   grid.pattern_pch(x_hex, y_hex, shape = 15:20, gp = gp,
+#'                    spacing = 0.1, density = 0.4, angle = 0)
+#' }
+#' if (capabilities("png") || guess_has_R4.1_features("masks")) {
+#'   # pch 21-25 are filled with 'fill'
+#'   grid::grid.newpage()
+#'   grid.pattern_pch(x_hex, y_hex, shape = 21:25, gp = gp,
+#'                    spacing = 0.1, density = 0.4, angle = 0)
+#' }
+#' if (capabilities("png") || guess_has_R4.1_features("masks")) {
+#'   # using a 'basket' weave `type` with two shapes
+#'   grid::grid.newpage()
+#'   grid.pattern_pch(x_hex, y_hex, shape = c(1,4), gp = gp,
+#'                    type = "basket",
+#'                    spacing = 0.1, density = 0.4, angle = 0)
+#' }
 #' @export
 grid.pattern_pch <- function(x = c(0, 0, 1, 1), y = c(1, 0, 0, 1), id = 1L, ...,
                                          colour = gp$col %||% "grey20",