spread: Spread boxes (S3)

In Gmisc: Descriptive Statistics, Transition Plots, and More

Spread boxes (S3)

Description

Spread a list of boxes vertically or horizontally. Designed for piping ('|>').

Spreads a set of boxGrob/boxPropGrob in either horizontal or vertical direction within a given span.

Usage

spread(x, ...)

## Default S3 method:
spread(x, ...)

## S3 method for class 'list'
spread(x, ...)

## S3 method for class 'Gmisc_list_of_boxes'
spread(x, ..., axis = c("y", "x", "vertical", "horizontal"))

spreadVertical(
  ...,
  from = NULL,
  to = NULL,
  margin = unit(0, "npc"),
  type = c("between", "center"),
  subelement = NULL
)

spreadHorizontal(
  ...,
  from = NULL,
  to = NULL,
  margin = unit(0, "npc"),
  type = c("between", "center"),
  subelement = NULL
)

Arguments

x	A 'list' of boxes.
...	A set of boxes to spread. Can also be a list of boxes.
axis	Orientation: '"y"'/'"vertical"' or '"x"'/'"horizontal"'.
from	Starting point of the span. Can be a box, a coordinate/unit, or a numeric value interpreted as npc. If only from is provided, to defaults to ⁠1 npc⁠.
to	Ending point of the span. Can be a box, a coordinate/unit, or a numeric value interpreted as npc. If only to is provided, from defaults to ⁠0 npc⁠.
margin	Optional padding applied at both ends of the span. Can be a grid::unit or a numeric value interpreted as npc. Applied whether the span comes from from / to or the viewport.
type	If between, the space between boxes is identical. If center, the centers of the boxes are equally distributed across the span.
subelement	If a list of boxes is provided, this parameter can be used to target a specific element (by name or index), or a deep path into nested lists (e.g., c("detail", 1)), for the spreading operation. You can also provide multiple targets by giving a list of paths (e.g., list(c("detail", 1), c("followup", 1))). The function will return the original list with the targeted element(s) replaced by their spread version(s).

Details

The span can be defined explicitly using from / to, or implicitly by the current viewport. Numeric values are interpreted as proportions of the viewport (npc units).

Value

The list of boxes with updated positions (class 'Gmisc_list_of_boxes').

A list with the boxes that have been spread.

See Also

Other flowchart components: align(), append(), boxGrob(), boxHeaderGrob(), boxPropGrob(), boxShapes, connectGrob(), coords(), distance(), flowchart(), insert(), move(), moveBox()

Other flowchart components: align(), append(), boxGrob(), boxHeaderGrob(), boxPropGrob(), boxShapes, connectGrob(), coords(), distance(), flowchart(), insert(), move(), moveBox()

Examples

library(grid)
grid.newpage()

# Create a set of boxes
start <- boxGrob("Top", x = .5, y = .8)
end <- boxGrob("Bottom", x = .5, y = .2)
side <- boxPropGrob("Side", "Left", "Right", prop = .3, x = .2, y = .8)
exclude <- boxGrob("Exclude:\n - Too sick\n - Prev. surgery", x = .8, y = .5, just = "left")

# We can chain the spread operations and print the result
spreadVertical(
  start = start,
  middle = list(side, exclude),
  end = end
) |>
  spreadHorizontal(subelement = "middle", from = 0.2, to = 0.8)

# Use device-level paging in interactive sessions so users can inspect the first plot
# This will prompt before creating the next page; we restore the previous setting afterwards
if (interactive()) {
  old_ask <- grDevices::devAskNewPage(TRUE)
  on.exit(grDevices::devAskNewPage(old_ask), add = TRUE)
  grid.newpage() # will prompt on interactive devices
} else {
  # non-interactive: just start a fresh page for the next example
  grid.newpage()
}

# Example: spread a nested subelement by deep path and print sequentially
list(grp = list(middle = list(side, exclude))) |>
  spreadHorizontal(subelement = c("grp", "middle"), from = 0.2, to = 0.8)

Gmisc documentation built on March 6, 2026, 9:09 a.m.