% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/paintr-builtins.R
\name{ppLayerOff}
\alias{ppLayerOff}
\title{Off-by-default layer wrapper}
\usage{
ppLayerOff(layer_expr, hide = TRUE)
}
\arguments{
\item{layer_expr}{A ggplot2 layer expression (e.g. \code{geom_point()},
\code{facet_wrap(~ cyl)}). Evaluated only when \code{hide = FALSE}.}

\item{hide}{A length-1 logical literal (\code{TRUE} or \code{FALSE}). In
\code{ptr_app()} formulas this MUST be a literal — the translator aborts
on a non-literal so the formula remains the single source of truth
for the app's boot state. Defaults to \code{TRUE}.}
}
\value{
Outside \code{ptr_app()}: \code{NULL} when \code{hide = TRUE}, otherwise the
evaluated \code{layer_expr}.
}
\description{
ADR-0020 \emph{structural} keyword that marks a layer as off-by-default in
\code{ptr_app()}. Inside \code{ptr_app()} / \code{ptr_server()} the parser sees the
wrapper and unwraps it at translate time, stamping the boot-state
metadata on the resulting node: \code{ppLayerOff(layer_expr, hide = TRUE)}
becomes a \code{ptr_layer} with \code{default_active = FALSE}. The wrapper
itself never appears in the typed tree.
}
\details{
Outside \code{ptr_app()} it behaves per its R semantics so naked-ggplot
scripts still render: \code{ppLayerOff(geom_point(), TRUE)} returns \code{NULL}
(so \code{ggplot(mtcars, aes(x = mpg, y = wt)) + ppLayerOff(geom_point(), TRUE)}
renders without the hidden layer); \code{ppLayerOff(geom_point(), FALSE)}
returns the layer.

For the pipeline-stage sibling that exposes a user-toggleable checkbox
(ADR-0021), see \code{\link[=ppVerbSwitch]{ppVerbSwitch()}}.
}
\examples{
library(ggplot2)
# Naked-R semantics: hide = TRUE drops the layer to NULL.
p1 <- ggplot(mtcars, aes(x = mpg, y = wt)) +
  ppLayerOff(geom_point(), TRUE)        # equivalent to no geom_point
p2 <- ggplot(mtcars, aes(x = mpg, y = wt)) +
  ppLayerOff(geom_point(), FALSE)       # the layer is added

# Inside ptr_app(), the wrapper becomes a node-level default and a
# boot-state-off checkbox:
if (interactive()) {
  ptr_app(ggplot() + ppLayerOff(geom_point(aes(x = mpg, y = wt)), TRUE))
}
}
