% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/alignpatch-.R
\docType{data}
\name{Patch-ggproto}
\alias{Patch-ggproto}
\alias{Patch}
\title{Patch object}
\description{
In \code{alignpatches()}, each subplot require a \code{Patch} object for proper
alignment and layout operations. \code{Patch} object is a
\code{\link[ggplot2:ggproto]{ggproto()}} object that provides the core methods for
arranging and aligning the plots.
}
\section{Fields}{

\describe{
\item{\code{options}}{A \code{\link{patch_options}} object used to align the plot.}

\item{\code{set_options}}{\strong{Description}

Sets multiple options at once in the \code{options} field. This method allows
you to provide one or more key-value pairs, where each key represents an
option name and its corresponding value is assigned to that option.

\strong{Arguments}
\itemize{
\item \code{...}: Key-value pairs to set specific properties of the \code{options}
object. Each argument should be of the form \code{name = value}, where
\code{name} is the option name and \code{value} is the value to assign to it.
}}

\item{\code{set_option}}{\strong{Description}

Sets a specific option in the \code{options} field. This method allows you to
modify individual properties of the \code{options} object by providing a
key-value pair.

\strong{Arguments}
\itemize{
\item \code{name}: The name of the option to be set (as a character string).
\item \code{value}: The value to assign to the specified option.
\item \code{check}: Logical, if \code{TRUE} (default), checks the validity of the
option before assigning it. Set to \code{FALSE} to bypass the check.
}}

\item{\code{get_option}}{\strong{Description}

Retrieves a specific option from the \code{options} field.

\strong{Arguments}
\itemize{
\item \code{option}: The name of the option to retrieve.
}

\strong{Value}
The value of the specified option.}

\item{\code{setup}}{\strong{Description}

(Optional method) Sets up the \code{options} and \code{data} for the plot.

\strong{Arguments}
\itemize{
\item \code{options}: A \code{\link{patch_options}} object that contains various layout
options.
}}

\item{\code{gtable}}{\strong{Description}

(Required method) Constructs a
\code{\link[=standardized_gtable]{standardized gtable}} object.

\strong{Value}
A standardized \code{\link[gtable:gtable]{gtable}} object, or a simple
\code{\link[grid:grid.grob]{grob}} object.

The returned object represents the graphical structure, which can either
be a full table-based layout (\code{gtable}) for more complex arrangements or
a simpler graphical object (\code{grob}) when only basic plot elements are
involved.}

\item{\code{decompose_guides}}{\strong{Description}

(Optional method) Collects guide legends and optionally removes the space
they occupy.

This method extracts guide legends based on the sides specified in the
\code{guides} argument. After collecting the guides, the corresponding space
in the \code{gt} is removed to free up space, except for guides placed
\code{inside} the panel.

\strong{Arguments}
\itemize{
\item \code{gt}: A \code{\link[gtable:gtable]{gtable}} object, usually returned by
\code{self$gtable()}.
}

\strong{Value}
A list with:
\itemize{
\item \code{gt}: The updated gtable with guide legends removed (if applicable).
\item \code{guides}: A named list of collected guide grobs corresponding to the
sides specified in \code{guides} (or \code{NULL} if absent).
}}

\item{\code{tag}}{Add a Tag to a \code{gtable}

\strong{Description}:
This function adds a tag to a given \code{gtable} at a specified position. The
tag is added only if the \code{gtable} is standardized (i.e., it has the
expected number of rows and columns)..

\strong{Arguments}:
\itemize{
\item \code{gt}: A \code{gtable} object to which the tag will be added.
\item \code{label}: A string representing the label or content for the tag.
\item \code{t}, \code{l}, \code{b}, \code{r}: Numeric values representing the top, left, bottom,
and right margins (coordinates) for placing the tag on the \code{gtable}.
\item \code{z}: A numeric value representing the z-order, controlling the stacking
order of the tag relative to other elements in the \code{gtable}.
}

\strong{Value}:
The modified \code{gtable} with the tag added. If the \code{gtable} is not
standardized (i.e., it doesn't meet the row/column requirements), the
function returns the original \code{gtable} without modification.}

\item{\code{panel_sizes}}{\strong{Description}

This method retrieves the panel sizes (widths and heights) of a \code{gtable}
or \code{grob} object.

\strong{Arguments}
\itemize{
\item \code{gt}: A \code{\link[gtable:gtable]{gtable}} object, usually returned by
\code{self$decompose_guides()}.
}

\strong{Value}
A list with components:
\itemize{
\item \code{widths}: The panel widths as a unit object
\item \code{heights}: The panel heights as a unit object
}}

\item{\code{adjust_panel_width/adjust_panel_height}}{\strong{Description}

(Optional method) In most cases, the panel sizes do not need to be
manually adjusted when aligning, as long as their border sizes are
consistent. However, for \code{\link[gtable:gtable]{gtable}} objects with absolute
panel sizes, the panel sizes must be directly set to ensure that all plot
panels fill in. This is particularly important when the specified and
desired panel sizes are in absolute units. The method is only called
when the plot does not span across multiple areas.

\strong{Arguments}
\itemize{
\item \code{panel_widths}/\code{panel_heights}: Unit objects representing the panel
widths or heights of the underlying \code{\link[gtable:gtable]{gtable}} object.
These values correspond to the \code{widths}/\code{heights} fields returned by
the \verb{$panel_sizes()} method.
\item \code{panel_width}/\code{panel_height}: Unit objects representing the desired
panel size. If the internal numeric value is \code{NA}, the size will be
computed based on \code{panel_widths}/\code{panel_heights}.
}

\strong{Value}
The panel width/height as a unit object}

\item{\code{respect_panel}}{\strong{Description}

(Optional method) In most cases, panel sizes do not need to be manually
adjusted when aligning panels, as long as their border sizes are
consistent. However, for \code{gtables} with a fixed panel aspect ratio, if
the internal \emph{numeric value} of the input panel sizes (either
\code{panel_width} or \code{panel_height} is \code{NA}), that dimension will be inferred
while maintaining the aspect ratio, particularly for single-panel
layouts.

\strong{Arguments}
\itemize{
\item \code{gt}: A \code{\link[gtable:gtable]{gtable}} object, usually returned by
\code{self$decompose_guides()}.
\item \code{panel_width}/\code{panel_height}: Unit objects specifying the desired panel
size. If the internal numeric value of either is \code{NA}, the size is
computed from the gtable (\code{gt}).
}

\strong{Value}
A list with components:
\itemize{
\item \code{width}: The panel width as a unit object
\item \code{height}: The panel height as a unit object
\item \code{respect}: If \code{TRUE}, the aspect ratio was enforced
}}

\item{\code{border_sizes}}{\strong{Description}

(Optional method) retrieve the border sizes of a gtable.

\strong{Arguments}
\itemize{
\item \code{gt}: A \code{\link[gtable:gtable]{gtable}} object, usually returned by
\code{self$decompose_guides()}.
}

\strong{Value}
A list with components:
\itemize{
\item \code{top}: \code{unit} values for the top borders or \code{NULL}.
\item \code{left}: \code{unit} values for the left borders or \code{NULL}.
\item \code{bottom}: \code{unit} values for the bottom borders or \code{NULL}.
\item \code{right}: \code{unit} values for the right borders or \code{NULL}.
}}

\item{\code{align_border}}{\strong{Description}

(Optional method) This method modifies the top, left, bottom, and right
border sizes of the underlying gtable (\code{gt}) by replacing corresponding
entries in its \code{heights} and \code{widths} vectors..

\strong{Arguments}
\itemize{
\item \code{gt}: A \code{\link[gtable:gtable]{gtable}} object, usually returned by
\code{self$decompose_guides()}.
\item \code{t}, \code{l}, \code{b}, \code{r}: Optional numeric vectors specifying new sizes for
the top, left, bottom, and right borders, respectively. Each vector
replaces the corresponding entries in \code{gt$heights} or \code{gt$widths}.
}

\strong{Value}
A modified \code{\link[gtable:gtable]{gtable}} object.}

\item{\code{place}}{\strong{Description}
(Optional method) Inserts the patch's gtable (including optional
background) into the target canvas gtable.

This method places the patch's gtable into a specified location of
another gtable, preserving the background and plot layers separately if a
background exists. The \code{t}, \code{l}, \code{b}, \code{r} arguments specify the position
in the target gtable, and \code{bg_z} / \code{plot_z} define the stacking order
(z-order) for background and plot.

\strong{Arguments}
\itemize{
\item \code{gtable}: the target canvas gtable into which the patch will be
inserted.
\item \code{gt}: A \code{\link[gtable:gtable]{gtable}} object, usually returned by
\code{self$align_border()}.
\item \code{t}, \code{l}, \code{b}, \code{r}: Integer positions (top, left, bottom, right)
specifying where to insert the patch in the target gtable.
\item \code{i}: Index of the current patch, used to generate unique grob names.
\item \code{bg_z}: Z-order for the background grob (default \code{1L}).
\item \code{plot_z}: Z-order for the plot grob (default \code{2L}).
\item \code{options}: A \code{\link{patch_options}} object containing various layout
options. Typically, this is the value returned by the subplot's
\code{self$setup()} method.
}

\strong{Details}
\itemize{
\item If the patch includes a grob named \code{"background"}, it is separated from
the main plot and inserted independently from the plot grob.
\item If no background is present, the entire gtable is inserted as the plot
grob.
}

\strong{Value}
The modified target canvas gtable with the patch's gtable added.}

\item{\code{decompose_bg}}{\strong{Description}
Separates the background grob (if present) from the main gtable.

\strong{Value}
A list with:
\itemize{
\item \code{bg}: The background grob (or \code{NULL} if absent)
\item \code{gt}: The gtable with background removed
}}

\item{\code{place_bg}}{\strong{Description}
Adds the background grob into the target gtable.}

\item{\code{place_gt}}{\strong{Description}
Adds the main plot gtable into the target gtable.}

\item{\code{is_alignpatches}}{\strong{Description}

Checks whether the object inherits from the \code{\link[=alignpatches]{alignpatches()}} \code{Patch}
representation.

If \code{TRUE}, the \code{self$alignpatches} will include \code{patches}, \code{gt_list},
and \code{borders_list}. For an example of how these are used, refer to the
\code{patch.ggalign_free_lab} function in the \code{alignpatch-free-lab.R} script.

\strong{Value}
Logical value (\code{TRUE} or \code{FALSE}) indicating whether \code{self} is a
\code{PatchAlignpatches} object.}
}}

\keyword{datasets}
