List available patterns

registered_patterns() returns a data frame of all available patterns i.e. those of {gridpattern}, the user, and loaded packages (it never loads any packages and neither does has_registered_pattern()). has_pattern() returns whether pattern names currently resolve to a pattern i.e. whether grid.pattern() / patternGrob() could use them. has_registered_pattern() returns whether pattern names are taken i.e. whether registered_patterns() lists a pattern with that name (for a bare name owned by anyone and for a qualified name owned by that owner) even if the name doesn't resolve (e.g. because of a conflict). Use has_registered_pattern() (not has_pattern()) to check that registering a pattern won't clobber (nor conflict with) a pre-existing pattern. See register_pattern() for how bare pattern names are resolved.

Usage

registered_patterns()

has_pattern(pattern)

has_registered_pattern(pattern)

Arguments

pattern

A character vector of bare pattern names "name" and/or qualified pattern names "owner::name". For has_pattern() a qualified name "pkg::name" (or a bare name preferred to a pattern of {pkg}, see prefer_pattern()) loads {pkg}'s namespace (if installed and not yet loaded) so it may register its patterns (like pkg::fn does).

Value

registered_patterns() returns a data frame with columns

name

The pattern name.

owner

The package that registered the pattern or "R_GlobalEnv" for the user.

kind

Either "geometry" or "array".

source

One of "builtin", "register_pattern", or "options".

active

Whether the bare name currently resolves to this pattern (without loading the package of a preferred pattern, see prefer_pattern()).

has_pattern() and has_registered_pattern() return a logical vector the same length as pattern. For has_pattern() a bare name with an unresolved conflict (see conflicting_patterns()) returns FALSE as does a user's qualified name "R_GlobalEnv::name" if the user has more than one pattern with that name (only possible via the legacy ggpattern_geometry_funcs / ggpattern_array_funcs options) but for has_registered_pattern() both return TRUE.

See also

register_pattern() to register patterns.

Examples

head(registered_patterns())
#>         name       owner     kind  source active
#> 1    ambient gridpattern    array builtin   TRUE
#> 2      aRtsy gridpattern geometry builtin   TRUE
#> 3     circle gridpattern geometry builtin   TRUE
#> 4 crosshatch gridpattern geometry builtin   TRUE
#> 5       fill gridpattern geometry builtin   TRUE
#> 6   gradient gridpattern geometry builtin   TRUE
has_pattern(c("stripe", "gridpattern::stripe", "polygon"))
#> [1]  TRUE  TRUE FALSE
has_registered_pattern(c("stripe", "gridpattern::stripe", "polygon"))
#> [1]  TRUE  TRUE FALSE

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))
}
# don't clobber (nor conflict with) any pre-existing "polygon" pattern
run_example <- !has_registered_pattern("polygon")
if (run_example) {
  register_pattern("polygon", create_pattern_polygon)
  print(subset(registered_patterns(), name == "polygon"))
}
#>       name       owner     kind           source active
#> 15 polygon R_GlobalEnv geometry register_pattern   TRUE
if (run_example) {
  print(has_pattern("polygon"))
}
#> [1] TRUE
if (run_example) {
  unregister_pattern("polygon")
}