diff --git a/NEWS.md b/NEWS.md index 6a9d993fe8..64e6d62125 100644 --- a/NEWS.md +++ b/NEWS.md @@ -33,6 +33,9 @@ * New `position_dodge2(group.row)` argument that can be set to `"many"` to dodge groups with more than one row, such as in `geom_violin()` (@teunbrand, #6663) +* `theme(strip.placement.x)` and `theme(strip.placement.y)` can be used for more + granular control of strip placement when facetting. These have existed for some + time but were not previously documented (@arcresu, #6827). # ggplot2 4.0.2 diff --git a/R/theme-sub.R b/R/theme-sub.R index f7644fc08d..15149074fb 100644 --- a/R/theme-sub.R +++ b/R/theme-sub.R @@ -149,7 +149,8 @@ theme_sub_plot <- function(..., background, title, title.position, subtitle, cap #' @export #' @describeIn subtheme Theme specification for facet strips. theme_sub_strip <- function(..., background, background.x, background.y, clip, - placement, text, text.x, text.x.bottom, text.x.top, + placement, placement.x, placement.y, + text, text.x, text.x.bottom, text.x.top, text.y, text.y.left, text.y.right, switch.pad.grid, switch.pad.wrap) { warn_dots_empty() diff --git a/R/theme.R b/R/theme.R index d263ff0fe6..5c602e0a6b 100644 --- a/R/theme.R +++ b/R/theme.R @@ -192,9 +192,11 @@ #' inherits from `rect`). Horizontal facet background (`strip.background.x`) #' & vertical facet background (`strip.background.y`) inherit from #' `strip.background` or can be specified separately -#' @param strip.placement placement of strip with respect to axes, -#' either "inside" or "outside". Only important when axes and strips are -#' on the same side of the plot. +#' @param strip.placement,strip.placement.x,strip.placement.y +#' placement of strip with respect to axes, either "inside" or "outside". +#' Only important when axes and strips are on the same side of the plot. +#' Horizontal (`strip.placement.x`) & vertical (`strip.placement.y`) placements +#' inherit from `strip.placement` or can be specified separately #' @param strip.clip should strip background edges and strip labels be clipped #' to the extend of the strip background? Options are `"on"` to clip, `"off"` #' to disable clipping or `"inherit"` (default) to take the clipping setting @@ -474,6 +476,8 @@ theme <- function(..., strip.background.y, strip.clip, strip.placement, + strip.placement.x, + strip.placement.y, strip.text, strip.text.x, strip.text.x.bottom, diff --git a/man/subtheme.Rd b/man/subtheme.Rd index 1200580280..0e24783b49 100644 --- a/man/subtheme.Rd +++ b/man/subtheme.Rd @@ -162,6 +162,8 @@ theme_sub_strip( background.y, clip, placement, + placement.x, + placement.y, text, text.x, text.x.bottom, @@ -176,7 +178,7 @@ theme_sub_strip( \arguments{ \item{...}{Not in use, expected to be empty.} -\item{axis.line, background, background.x, background.y, border, box, box.background, box.just, box.margin, box.spacing, byrow, caption, caption.position, clip, direction, frame, grid, grid.major, grid.major.x, grid.major.y, grid.minor, grid.minor.x, grid.minor.y, heights, justification, justification.bottom, justification.inside, justification.left, justification.right, justification.top, key, key.height, key.justification, key.size, key.spacing, key.spacing.x, key.spacing.y, key.width, line, location, margin, minor.ticks, minor.ticks.length, ontop, placement, position, position.inside, spacing, spacing.x, spacing.y, subtitle, switch.pad.grid, switch.pad.wrap, tag, tag.location, tag.position, text, text.position, text.x, text.x.bottom, text.x.top, text.y, text.y.left, text.y.right, ticks, ticks.length, title, title.position, widths}{Arguments that are renamed and passed on to \code{\link[=theme]{theme()}}.} +\item{axis.line, background, background.x, background.y, border, box, box.background, box.just, box.margin, box.spacing, byrow, caption, caption.position, clip, direction, frame, grid, grid.major, grid.major.x, grid.major.y, grid.minor, grid.minor.x, grid.minor.y, heights, justification, justification.bottom, justification.inside, justification.left, justification.right, justification.top, key, key.height, key.justification, key.size, key.spacing, key.spacing.x, key.spacing.y, key.width, line, location, margin, minor.ticks, minor.ticks.length, ontop, placement, placement.x, placement.y, position, position.inside, spacing, spacing.x, spacing.y, subtitle, switch.pad.grid, switch.pad.wrap, tag, tag.location, tag.position, text, text.position, text.x, text.x.bottom, text.x.top, text.y, text.y.left, text.y.right, ticks, ticks.length, title, title.position, widths}{Arguments that are renamed and passed on to \code{\link[=theme]{theme()}}.} } \value{ A \code{theme}-class object that can be added to a plot. diff --git a/man/theme.Rd b/man/theme.Rd index 66a9be0d32..d3e1ee77e2 100644 --- a/man/theme.Rd +++ b/man/theme.Rd @@ -141,6 +141,8 @@ theme( strip.background.y, strip.clip, strip.placement, + strip.placement.x, + strip.placement.y, strip.text, strip.text.x, strip.text.x.bottom, @@ -378,9 +380,10 @@ to the extend of the strip background? Options are \code{"on"} to clip, \code{"o to disable clipping or \code{"inherit"} (default) to take the clipping setting from the parent viewport.} -\item{strip.placement}{placement of strip with respect to axes, -either "inside" or "outside". Only important when axes and strips are -on the same side of the plot.} +\item{strip.placement, strip.placement.x, strip.placement.y}{placement of strip with respect to axes, either "inside" or "outside". +Only important when axes and strips are on the same side of the plot. +Horizontal (\code{strip.placement.x}) & vertical (\code{strip.placement.y}) placements +inherit from \code{strip.placement} or can be specified separately} \item{strip.text, strip.text.x, strip.text.y, strip.text.x.top, strip.text.x.bottom, strip.text.y.left, strip.text.y.right}{facet labels (\code{\link[=element_text]{element_text()}}; inherits from \code{text}). Horizontal facet labels (\code{strip.text.x}) & vertical facet labels (\code{strip.text.y}) inherit from \code{strip.text} or can be specified diff --git a/tests/testthat/_snaps/theme.md b/tests/testthat/_snaps/theme.md index d3e0689d76..8e19457aee 100644 --- a/tests/testthat/_snaps/theme.md +++ b/tests/testthat/_snaps/theme.md @@ -58,3 +58,16 @@ Unknown arguments to `element_text()`: `italic`, `fontweight`, and `fontwidth`. +# all expected theme elements are documented + + Code + extra_elements + Output + [1] "palette.colour.discrete" "palette.colour.continuous" + [3] "palette.fill.discrete" "palette.fill.continuous" + [5] "palette.alpha.discrete" "palette.alpha.continuous" + [7] "palette.linewidth.discrete" "palette.linewidth.continuous" + [9] "palette.size.discrete" "palette.size.continuous" + [11] "palette.shape.discrete" "palette.shape.continuous" + [13] "palette.linetype.discrete" "palette.linetype.continuous" + diff --git a/tests/testthat/test-theme.R b/tests/testthat/test-theme.R index 55f9b8d47d..a6272c6e2a 100644 --- a/tests/testthat/test-theme.R +++ b/tests/testthat/test-theme.R @@ -693,3 +693,8 @@ test_that("legends are placed correctly when using stretchy spacing", { p + theme(legend.position = "top", legend.spacing.x = unit(1, "null")) ) }) + +test_that("all expected theme elements are documented", { + extra_elements <- setdiff(names(.element_tree), fn_fmls_names(theme)) + expect_snapshot(extra_elements) +})