Element list constructors

These functions take a vector of arguments and pass on the i^th item of the vector to an i^th call of a function. The elem_list_text and elem_list_rect are convenience functions for constructing lists of element_text() and element_rect() theme elements.

Usage

distribute_args(..., .fun = element_text, .cull = TRUE)

elem_list_text(...)

elem_list_rect(...)

Arguments

...

Vectorised arguments to pass on to functions.

.fun

A function to distribute arguments to.

.cull

A logical(1) determining if unknown arguments are being culled.

Value

A list of outputs from fun.

Details

NAs and NULLs will be silently dropped. If you want to pass on a transparent fill or colour argument, you should use the more verbose character "transparent" instead. However, you can use a NA to indicate that it's argument should not be passed to a function in that position.

Note

Whereas the distribute_args function might seem amenable for off-label uses elsewhere (besides constructing lists of theme elements), it is not intended as such. For example, because valid arguments will be deduced from the formals of a function, using certain functions can be troublesome. For example, the distribute_args function does not properly recognise the utility of a ... argument in a function that it is supposed to distribute arguments to. This can be a problem for object-oriented functions: if the methods contain more arguments than the generic itself, these extra arguments will be silently dropped.

See also

The element_text() and element_rect() theme elements for a description of their arguments.

Examples

# Providing arguments for `element_rect()`
elem_list_rect(
  # The first element_rect will have linetype 1, the second gets 3
  linetype = c(1, 3),
  # If an argument doesn't exist, it will be silently dropped
  nonsense_argument = c("I", "will", "be", "filtered", "out")
)
#> [[1]]
#> <ggplot2::element_rect>
#>  @ fill         : NULL
#>  @ colour       : NULL
#>  @ linewidth    : NULL
#>  @ linetype     : num 1
#>  @ linejoin     : NULL
#>  @ inherit.blank: logi FALSE
#> 
#> [[2]]
#> <ggplot2::element_rect>
#>  @ fill         : NULL
#>  @ colour       : NULL
#>  @ linewidth    : NULL
#>  @ linetype     : num 3
#>  @ linejoin     : NULL
#>  @ inherit.blank: logi FALSE
#> 

# Providing arguments for `element_text()`
elem_list_text(
  # `NA`s will be skipped
  family = c("mono", NA, "sans"),
  # Providing a list of more complex arguments. `NULL` will be skipped too.
  margin = list(NULL, margin(t = 5))
)
#> [[1]]
#> <ggplot2::element_text>
#>  @ family       : chr "mono"
#>  @ face         : NULL
#>  @ italic       : chr NA
#>  @ fontweight   : num NA
#>  @ fontwidth    : num NA
#>  @ colour       : NULL
#>  @ size         : NULL
#>  @ hjust        : NULL
#>  @ vjust        : NULL
#>  @ angle        : NULL
#>  @ lineheight   : NULL
#>  @ margin       : NULL
#>  @ debug        : NULL
#>  @ inherit.blank: logi FALSE
#> 
#> [[2]]
#> <ggplot2::element_text>
#>  @ family       : NULL
#>  @ face         : NULL
#>  @ italic       : chr NA
#>  @ fontweight   : num NA
#>  @ fontwidth    : num NA
#>  @ colour       : NULL
#>  @ size         : NULL
#>  @ hjust        : NULL
#>  @ vjust        : NULL
#>  @ angle        : NULL
#>  @ lineheight   : NULL
#>  @ margin       : <ggplot2::margin> num [1:4] 5 0 0 0
#>  @ debug        : NULL
#>  @ inherit.blank: logi FALSE
#> 
#> [[3]]
#> <ggplot2::element_text>
#>  @ family       : chr "sans"
#>  @ face         : NULL
#>  @ italic       : chr NA
#>  @ fontweight   : num NA
#>  @ fontwidth    : num NA
#>  @ colour       : NULL
#>  @ size         : NULL
#>  @ hjust        : NULL
#>  @ vjust        : NULL
#>  @ angle        : NULL
#>  @ lineheight   : NULL
#>  @ margin       : NULL
#>  @ debug        : NULL
#>  @ inherit.blank: logi FALSE
#> 

# Providing arguments to other functions
distribute_args(
  lineend = c("round", "butt", "square"),
  # If you want to pass a vector instead of a scalar, you can use a list
  colour = list(c("blue", "red"), "green"),
  .fun = element_line
)
#> [[1]]
#> <ggplot2::element_line>
#>  @ colour       : chr [1:2] "blue" "red"
#>  @ linewidth    : NULL
#>  @ linetype     : NULL
#>  @ lineend      : chr "round"
#>  @ linejoin     : NULL
#>  @ arrow        : logi FALSE
#>  @ arrow.fill   : chr [1:2] "blue" "red"
#>  @ inherit.blank: logi FALSE
#> 
#> [[2]]
#> <ggplot2::element_line>
#>  @ colour       : chr "green"
#>  @ linewidth    : NULL
#>  @ linetype     : NULL
#>  @ lineend      : chr "butt"
#>  @ linejoin     : NULL
#>  @ arrow        : logi FALSE
#>  @ arrow.fill   : chr "green"
#>  @ inherit.blank: logi FALSE
#> 
#> [[3]]
#> <ggplot2::element_line>
#>  @ colour       : NULL
#>  @ linewidth    : NULL
#>  @ linetype     : NULL
#>  @ lineend      : chr "square"
#>  @ linejoin     : NULL
#>  @ arrow        : logi FALSE
#>  @ arrow.fill   : NULL
#>  @ inherit.blank: logi FALSE
#>