Skip to contents

Temporarily register a pattern

Source: R/registry.R
local_pattern.Rd

local_pattern() registers a pattern (see register_pattern()) until the current function (or test, see .local_envir) exits and then restores the previous registration (if any). Requires the suggested {withr} package.

Usage

local_pattern(
  name,
  fn,
  kind = c("geometry", "array"),
  defaults = list(),
  unprefixed = character(),
  env = caller_env(),
  .local_envir = parent.frame()
)

Arguments

name

Pattern name. Must not contain ":".

fn

Pattern function. Its required signature depends on kind:

geometry

function(params, boundary_df, aspect_ratio, legend) returning a grid grob that lies within the boundary (e.g. clipped to it). params is a list of (prefixed) pattern parameters e.g. params$pattern_fill, boundary_df is a data frame with x, y, and id columns describing the boundary polygon(s) in “npc” coordinates, aspect_ratio is the (best guess) aspect ratio of the viewport, and legend is whether the pattern is being drawn in a {ggpattern} legend key.

array

function(width, height, params, legend) returning a 3D array of RGBA values (all values in the range [0, 1]) which {gridpattern} will mask to the boundary. width and height are the dimensions (in pixels) of the boundary's bounding box and params and legend are as for geometry patterns.

See the “Developing Patterns” vignette vignette("developing-patterns", package = "gridpattern") for more details and examples.

kind

Either "geometry" or "array".

defaults

A named list of pattern-specific default parameter values e.g. list(pattern_type = "running", pattern_spacing = 0.1). Names are used as-is and must be pattern_ prefixed unless listed in unprefixed. Values may be constants or functions of the form function(params, gp) where params is the list of pattern parameters filled in so far and gp is the grob's grid::gpar() object e.g. list(pattern_amplitude = function(params, gp) 0.5 * params$pattern_spacing) or list(pattern_size = function(params, gp) gp$fontsize %||% 12). These replace the generic defaults for parameters that weren't supplied. The remaining generic defaults are filled in first and then these in the order given so a function default may use any generic parameter and any earlier pattern-specific default. Note {ggpattern} supplies its own (generic) defaults for most of its pattern aesthetics so these will mainly be used with grid.pattern() / patternGrob().

unprefixed

A character vector of parameter names without the pattern_ prefix that the pattern reads so that defaults may set them. The usual case is a plain {ggplot2} aesthetic that {ggpattern} passes to pattern functions alongside the pattern_ aesthetics e.g. defaults = list(fill = "black"), unprefixed = "fill" lets a pattern that reads params$fill under {ggpattern} also work with grid.pattern(). Since such patterns are rare any other unprefixed name (e.g. fill or spacing instead of pattern_fill or pattern_spacing) is an error of class "gridpattern_error_unprefixed_defaults".

env

The environment used to determine the “owner” of the pattern. If writing a function that registers patterns on behalf of its caller add an env = rlang::caller_env() argument to that function and pass it on.

.local_envir

The environment whose exit should undo local_pattern()'s registration.

Value

local_pattern() invisibly returns the previous registration (a list) or NULL if there wasn't one.

See also

register_pattern() to (permanently) register patterns.

Examples

create_pattern_polygon <- function(params, boundary_df, aspect_ratio, legend = FALSE) {
  grid::polygonGrob(boundary_df$x, boundary_df$y, boundary_df$id,
                    gp = grid::gpar(fill = params$pattern_fill))
}
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))
draw_polygon <- function() {
  local_pattern("polygon", create_pattern_polygon)
  grid::grid.newpage()
  grid.pattern("polygon", x_hex, y_hex, fill = "red")
}
# don't clobber (or be confused by) any pre-existing "polygon" pattern
if (requireNamespace("withr", quietly = TRUE) && !has_pattern("polygon")) {
  draw_polygon()
}

print(has_pattern("polygon"))
#> [1] FALSE