% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/boxGrobs_s3_spread.R, R/boxGrobs_spread.R
\name{spread}
\alias{spread}
\alias{spread.default}
\alias{spread.list}
\alias{spread.Gmisc_list_of_boxes}
\alias{spreadVertical}
\alias{spreadHorizontal}
\title{Spread boxes (S3)}
\usage{
spread(x, ...)

\method{spread}{default}(x, ...)

\method{spread}{list}(x, ...)

\method{spread}{Gmisc_list_of_boxes}(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{
\item{x}{A `list` of boxes.}

\item{...}{A set of boxes to spread. Can also be a \code{list} of boxes.}

\item{axis}{Orientation: `"y"`/`"vertical"` or `"x"`/`"horizontal"`.}

\item{from}{Starting point of the span. Can be a box, a coordinate/unit, or a
numeric value interpreted as \code{npc}. If only \code{from} is provided, \code{to} defaults
to \verb{1 npc}.}

\item{to}{Ending point of the span. Can be a box, a coordinate/unit, or a
numeric value interpreted as \code{npc}. If only \code{to} is provided, \code{from} defaults
to \verb{0 npc}.}

\item{margin}{Optional padding applied at both ends of the span. Can be a
\code{\link[grid:unit]{grid::unit}} or a numeric value interpreted as \code{npc}. Applied whether the
span comes from \code{from} / \code{to} or the viewport.}

\item{type}{If \code{between}, the space \emph{between} boxes is identical. If \code{center},
the centers of the boxes are equally distributed across the span.}

\item{subelement}{If a \code{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., \code{c("detail", 1)}), for the spreading operation. You can also
provide multiple targets by giving a list of paths (e.g., \code{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).}
}
\value{
The list of boxes with updated positions (class `Gmisc_list_of_boxes`).

A \code{list} with the boxes that have been spread.
}
\description{
Spread a list of boxes vertically or horizontally. Designed for piping (`|>`).

Spreads a set of \code{\link{boxGrob}}/\code{\link{boxPropGrob}} in either horizontal or vertical
direction within a given span.
}
\details{
The span can be defined explicitly using \code{from} / \code{to}, or implicitly by the
current viewport. Numeric values are interpreted as proportions of the viewport
(\code{npc} units).
}
\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)
}
\seealso{
Other flowchart components:
\code{\link[=align]{align()}},
\code{\link[=append]{append()}},
\code{\link[=boxGrob]{boxGrob()}},
\code{\link[=boxHeaderGrob]{boxHeaderGrob()}},
\code{\link[=boxPropGrob]{boxPropGrob()}},
\code{\link{boxShapes}},
\code{\link[=connectGrob]{connectGrob()}},
\code{\link[=coords]{coords()}},
\code{\link[=distance]{distance()}},
\code{\link[=equalizeWidths]{equalizeWidths()}},
\code{\link[=flowchart]{flowchart()}},
\code{\link[=insert]{insert()}},
\code{\link[=move]{move()}},
\code{\link[=moveBox]{moveBox()}}
}
\concept{flowchart components}
