% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/boxGrobs_align.R, R/boxGrobs_s3_align.R
\name{align}
\alias{align}
\alias{alignVertical}
\alias{alignHorizontal}
\alias{align.default}
\alias{align.list}
\alias{align.Gmisc_list_of_boxes}
\title{Align boxes}
\usage{
alignVertical(
  reference,
  ...,
  position = c("center", "top", "bottom"),
  subelement = NULL
)

alignHorizontal(
  reference,
  ...,
  position = c("center", "left", "right"),
  sub_position = c("none", "left", "right"),
  subelement = NULL
)

align(x, ...)

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

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

\method{align}{Gmisc_list_of_boxes}(x, ..., axis = c("y", "x", "vertical", "horizontal"))
}
\arguments{
\item{reference}{A \code{\link{boxGrob}}/\code{\link{boxPropGrob}}/\code{\link{coords}} object or a \code{\link[grid:unit]{unit}} or a
numerical value that can be converted into a \code{\link[grid:unit]{unit}} of \code{npc} type. If a numeric scalar is
provided and is \code{0} or greater than the number of boxes, it is treated as a coordinate (no error is raised).}

\item{...}{Arguments passed to [`alignVertical`] or [`alignHorizontal`].}

\item{position}{How to align the boxes, differs slightly for vertical and horizontal alignment
see the accepted arguments}

\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 alignment operation. You can also
provide multiple targets by giving a list of paths (e.g., \code{list(c("detail", 1), c("followup", 1))}).
When a list of boxes is \emph{piped} into \code{alignVertical()}/\code{alignHorizontal()} and a named \code{reference} is
provided (e.g. \code{my_boxes |> alignHorizontal(reference = c("grp","sub"), .subelement = ...)}), the
function will unwrap a single-element wrapper so nested \code{.subelement} targets are found as expected.
The function will return the original list with the targeted element(s)
replaced by their aligned version(s).}

\item{sub_position}{When the box is a \code{\link{boxPropGrob}} it not only has the general \code{.positions} but
also \code{left} and \code{right} which can be viewed as separate boxes that have simply been merged.}

\item{x}{A `list` of boxes.}

\item{axis}{Orientation: `"y"`/`"vertical"` or `"x"`/`"horizontal"`.}
}
\value{
\code{list} with the boxes that are to be aligned

The aligned list of boxes (class `Gmisc_list_of_boxes`).
}
\description{
Aligns a set of \code{\link{boxGrob}}/\code{\link{boxPropGrob}} according to the first positional argument.

Align a list of boxes vertically or horizontally. Designed for piping (`|>`).
}
\examples{
library(grid)
grid.newpage()

# Create a reference box
box <- boxGrob("A cool reference box",
  x = .5, y = .8,
  box_gp = gpar(fill = "#ADB5C7")
)

# Create a group of boxes to align
boxes <- list(
  another_box = boxGrob("A horizontal box", x = .1, y = .5),
  yet_another_box = boxGrob("Another horizontal box", x = .8, y = .3)
)

# Align the group and then individual boxes within that group
# (do not pipe the list into the function, as the first argument is `reference`)
aligned_boxes <- alignHorizontal(boxes, reference = box, position = "right") |>
  alignVertical(reference = .5, position = "center")

# Example: align a nested element inside a complex list using a deep path
complex_list <- list(
  arms = list(
    early = list(boxGrob("Early", x = .2, y = .4)),
    late = list(boxGrob("Late", x = .8, y = .2))
  ),
  detail = list(
    list(boxGrob("D_early", x = .1, y = .6)),
    list(boxGrob("D_late", x = .9, y = .1))
  )
)

# Align the first detail element to the early arm by deep path
complex_list <- complex_list |>
  alignHorizontal(
    reference = c("arms", "early"),
    position = "center",
    subelement = c("detail", 1)
  )

# Print the reference and the aligned boxes
box
aligned_boxes
complex_list
}
\seealso{
Other flowchart components:
\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()}},
\code{\link[=spread]{spread()}}
}
\concept{flowchart components}
