New 'line' pattern

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: gridpattern
 Type: Package
 Title: 'grid' Pattern Grobs
-Version: 1.3.3-3
+Version: 1.4.0-1
 Authors@R: c(
         person("Trevor L.", "Davis", role=c("aut", "cre"), email="trevor.l.davis@gmail.com",
                comment = c(ORCID = "0000-0001-6341-4639")),
@@ -13,7 +13,6 @@ BugReports: https://github.com/trevorld/gridpattern/issues
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.3
 Depends:
     R (>= 3.4.0)
 Imports:
@@ -39,3 +38,4 @@ Suggests:
     testthat,
     vdiffr (>= 1.0.6)
 VignetteBuilder: knitr, rmarkdown
+Config/roxygen2/version: 8.0.0

NAMESPACE

@@ -20,6 +20,7 @@ export(grid.pattern_crosshatch)
 export(grid.pattern_fill)
 export(grid.pattern_gradient)
 export(grid.pattern_image)
+export(grid.pattern_line)
 export(grid.pattern_magick)
 export(grid.pattern_none)
 export(grid.pattern_pch)

NEWS.md

@@ -1,6 +1,15 @@
-gridpattern v1.3.3 (development)
+gridpattern v1.4.0 (development)
 ================================
 
+New Features
+------------
+
+* New "line" pattern with corresponding `grid.pattern_line()`.
+  Unlike the "stripe" pattern which fills bands with solid colour,
+  "line" draws stroked lines using the device's native line rendering,
+  enabling all of R's built-in `linetype` values
+  (including `"dotdash"`, `"twodash"`, and custom line types specified as hex strings per `?par`).
+
 Bug fixes and minor improvements
 --------------------------------
 

R/grid-pattern.R

@@ -19,6 +19,8 @@
 #'                 See [grid.pattern_gradient()] for more information.}
 #' \item{image}{Image array patterns.
 #'              See [grid.pattern_image()] for more information.}
+#' \item{line}{Line geometry patterns.
+#'             See [grid.pattern_line()] for more information.}
 #' \item{magick}{`imagemagick` array patterns.
 #'               See [grid.pattern_magick()] for more information.}
 #' \item{none}{Does nothing.
@@ -157,6 +159,7 @@ names_pattern <- c(
 	"fill",
 	"gradient",
 	"image",
+	"line",
 	"magick",
 	"none",
 	"pch",
@@ -248,6 +251,7 @@ get_pattern_fn <- function(pattern) {
 			crosshatch = create_pattern_crosshatch_via_sf,
 			fill = create_pattern_fill,
 			gradient = create_pattern_gradient,
+			line = create_pattern_line,
 			none = create_pattern_none,
 			pch = create_pattern_pch,
 			polygon_tiling = create_pattern_polygon_tiling,

R/pattern-both-line.R

@@ -0,0 +1,130 @@
+#' Line patterned grobs
+#'
+#' `grid.pattern_line()` draws a line pattern onto the graphic device.
+#' Unlike [grid.pattern_stripe()] which fills bands with solid colour,
+#' this pattern draws stroked lines using the device's native line rendering,
+#' enabling all of R's built-in `linetype` values (including `"dotdash"`,
+#' `"twodash"`, and custom line types specified as hex strings per `?par`).
+#'
+#' @inheritParams grid.pattern_circle
+#' @inheritParams alphaMaskGrob
+#' @param lineend Line end style, one of `"round"` (default), `"butt"`, or `"square"`.
+#' @return A grid grob object invisibly.  If `draw` is `TRUE` then also draws to the graphic device as a side effect.
+#' @examples
+#' 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))
+#' if (capabilities("png") || guess_has_R4.1_features("masks")) {
+#'   grid::grid.newpage()
+#'   grid.pattern_line(x_hex, y_hex, colour = "black", angle = 0, spacing = 0.1)
+#' }
+#'
+#' if (capabilities("png") || guess_has_R4.1_features("masks")) {
+#'   grid::grid.newpage()
+#'   grid.pattern_line(x_hex, y_hex, colour = "black", linetype = "dotdash",
+#'                     angle = 45, spacing = 0.1)
+#' }
+#'
+#' # more intricate dashed lines are possible with hex strings
+#' if (capabilities("png") || guess_has_R4.1_features("masks")) {
+#'   grid::grid.newpage()
+#'   grid.pattern_line(x_hex, y_hex, gp = grid::gpar(col = "darkred", lty = "23632E"))
+#' }
+#' @seealso [grid.pattern_stripe()] for filled bands, [grid.pattern_crosshatch()] for two sets of lines.
+#' @export
+grid.pattern_line <- function(
+	x = c(0, 0, 1, 1),
+	y = c(1, 0, 0, 1),
+	id = 1L,
+	...,
+	colour = gp$col %||% "grey20",
+	angle = 30,
+	spacing = 0.05,
+	xoffset = 0,
+	yoffset = 0,
+	units = "snpc",
+	alpha = gp$alpha %||% NA_real_,
+	lineend = gp$lineend %||% "round",
+	linetype = gp$lty %||% 1,
+	linewidth = size %||% gp$lwd %||% 1,
+	size = NULL,
+	use_R4.1_masks = getOption(
+		"ggpattern_use_R4.1_masks",
+		getOption("ggpattern_use_R4.1_features")
+	),
+	png_device = NULL,
+	res = getOption("ggpattern_res", 72),
+	default.units = "npc",
+	name = NULL,
+	gp = gpar(),
+	draw = TRUE,
+	vp = NULL
+) {
+	if (missing(colour) && hasName(l <- list(...), "color")) {
+		colour <- l$color
+	}
+	grid.pattern(
+		"line",
+		x,
+		y,
+		id,
+		colour = colour,
+		angle = angle,
+		spacing = spacing,
+		xoffset = xoffset,
+		yoffset = yoffset,
+		units = units,
+		alpha = alpha,
+		linetype = linetype,
+		linewidth = linewidth,
+		lineend = lineend,
+		use_R4.1_masks = use_R4.1_masks,
+		png_device = png_device,
+		res = res,
+		default.units = default.units,
+		name = name,
+		gp = gp,
+		draw = draw,
+		vp = vp
+	)
+}
+
+create_pattern_line <- function(params, boundary_df, aspect_ratio, legend = FALSE) {
+	default.units <- "bigpts"
+	boundary_df <- convert_polygon_df_units(boundary_df, default.units)
+	params <- convert_params_units(params, default.units)
+	vpm <- get_vp_measurements(default.units)
+	grid_xy <- get_xy_grid(params, vpm)
+
+	col <- update_alpha(params$pattern_colour, params$pattern_alpha)
+	lwd <- params$pattern_linewidth * .pt
+	lty <- params$pattern_linetype
+	lineend <- params$pattern_lineend
+	gp <- gpar(col = col, lwd = lwd, lty = lty, lineend = lineend)
+
+	x0 <- rep(grid_xy$x_min, length(grid_xy$y))
+	x1 <- rep(grid_xy$x_max, length(grid_xy$y))
+	xy0 <- rotate_xy(x0, grid_xy$y, params$pattern_angle, vpm$x, vpm$y)
+	xy1 <- rotate_xy(x1, grid_xy$y, params$pattern_angle, vpm$x, vpm$y)
+
+	maskee <- segmentsGrob(
+		xy0$x,
+		xy0$y,
+		xy1$x,
+		xy1$y,
+		default.units = default.units,
+		gp = gp
+	)
+	masker <- convert_polygon_df_to_polygon_grob(
+		boundary_df,
+		default.units = default.units,
+		gp = gpar(fill = "white", col = NA, lwd = 0)
+	)
+	alphaMaskGrob(
+		maskee,
+		masker,
+		use_R4.1_masks = params$pattern_use_R4.1_masks,
+		png_device = params$pattern_png_device,
+		res = params$pattern_res,
+		name = "line"
+	)
+}

R/pattern-geometry-stripe.R

@@ -15,6 +15,7 @@
 #' grid.pattern_stripe(x_hex, y_hex, density = 0.3,
 #'                     gp = grid::gpar(col = "blue", fill = "yellow"))
 #' @seealso `[grid.pattern_crosshatch()]` and `[grid.pattern_weave()]` for overlaying stripes.
+#'          Use [grid.pattern_line()] for stroked lines that support all native `linetype` values.
 #' @export
 grid.pattern_stripe <- function(
 	x = c(0, 0, 1, 1),

R/utils-params.R

@@ -10,6 +10,7 @@ get_params <- function(..., pattern = "none", prefix = "pattern_", gp = gpar())
 	l$pattern_alpha <- l$pattern_alpha %||% gp$alpha %||% NA_real_
 	l$pattern_colour <- l$pattern_colour %||% l$pattern_color %||% gp$col %||% "grey20"
 	l$pattern_fill <- l[["pattern_fill"]] %||% gp$fill %||% "grey80"
+	l$pattern_lineend <- l$pattern_lineend %||% gp$lineend %||% "round"
 	l$pattern_linetype <- l$pattern_linetype %||% gp$lty %||% 1
 	l$pattern_linewidth <- l$pattern_linewidth %||% l$pattern_size %||% gp$lwd %||% 1
 	if (pattern == "text") {

README.Rmd

@@ -35,6 +35,7 @@ as well as original "pch", "polygon_tiling", "regular_polygon", "rose", "text",
 1. [fill](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_fill.html): simple fill patterns
 1. [gradient](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_gradient.html): gradient array/geometry patterns
 1. [image](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_image.html): image array patterns
+1. [line](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_line.html): line geometry patterns
 1. [magick](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_magick.html): imagemagick array patterns
 1. [none](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_none.html): draws nothing
 1. [placeholder](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_placeholder.html): placeholder image array patterns

README.md

@@ -35,6 +35,7 @@ as well as original "pch", "polygon_tiling", "regular_polygon", "rose", "text",
 1. [fill](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_fill.html): simple fill patterns
 1. [gradient](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_gradient.html): gradient array/geometry patterns
 1. [image](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_image.html): image array patterns
+1. [line](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_line.html): line geometry patterns
 1. [magick](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_magick.html): imagemagick array patterns
 1. [none](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_none.html): draws nothing
 1. [placeholder](https://trevorldavis.com/R/gridpattern/dev/reference/grid.pattern_placeholder.html): placeholder image array patterns

_pkgdown.yml

@@ -4,6 +4,7 @@ development:
     mode: auto
 template:
   bootstrap: 5
+llm-docs: false
 reference:
     - title: "Pattern fills"
       desc: "Pattern fill function"