% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/paintr-app.R
\name{ptr_ui_controls}
\alias{ptr_ui_controls}
\title{Controls Piece for a \code{ggpaintr} Formula}
\usage{
ptr_ui_controls(
  formula,
  id = NULL,
  envir = parent.frame(),
  ui_text = NULL,
  expr_check = TRUE,
  shared = NULL
)
}
\arguments{
\item{formula}{Either a single character scalar containing a ggplot
expression with \code{ggpaintr} placeholders, or an unquoted / \verb{!!}-spliced
ggplot expression, captured with \code{\link[rlang:defusing-advanced]{rlang::enexpr()}} exactly as
\code{\link[=ptr_app]{ptr_app()}} / \code{\link[=ptr_server]{ptr_server()}}. See \code{\link[=ptr_app]{ptr_app()}} for the full contract.}

\item{id}{Optional module id; the namespace prefix for inputs.
Defaults to \code{NULL} (identity namespace). When set, must match the
\code{id} passed to the other piece functions and the server wiring.}

\item{envir}{Environment used to resolve a \code{formula} passed as a bare
symbol and any local data objects. Defaults to the calling frame.}

\item{ui_text}{Optional named list of copy overrides; see
\code{\link[=ptr_ui_text]{ptr_ui_text()}} for the full schema and current defaults.}

\item{expr_check}{Controls formula-level \code{ppExpr} validation: \code{TRUE}
(default) applies the built-in denylist + AST walker; \code{FALSE} disables
formula-level validation; a \code{list} with \code{deny_list}/\code{allow_list} entries
customises the formula-level policy. Runtime-typed \code{ppExpr} input is
always screened against the built-in denylist regardless. See the
safety chapter of the ggpaintr book (development-version docs):
\url{https://willju-wangqian.github.io/ggpaintr-book/safety.html}.}

\item{shared}{Optional coordinator object from \code{\link[=ptr_shared]{ptr_shared()}} for the
multi-instance embedding. When \code{NULL} (the single-instance default)
the inline "Shared controls" section renders \strong{every} \code{shared = "..."} placeholder in \code{formula}. When a \code{ptr_shared_spec} is supplied,
its cross-formula keys (\code{shared$panel_keys}) are excluded here because
they belong to the one standalone \code{\link[=ptr_shared_panel]{ptr_shared_panel()}}; only this
formula's formula-local shared keys render inline.}
}
\value{
A \code{\link[shiny:reexports]{shiny::tagList()}}.
}
\description{
The generated control widgets (layer picker, per-layer parameter
panels, the "Update plot" button) as a bare \code{\link[shiny:reexports]{shiny::tagList()}} with
\strong{no} \code{.ptr-app} wrapper and \strong{no} bundled assets. One of the
single-piece UI builders for the L3 "own every UI piece" workflow:
compose it with \code{\link[=ptr_ui_assets]{ptr_ui_assets()}} and the output pieces, place each
wherever you like, and wire the server with \code{\link[=ptr_server]{ptr_server()}} /
\code{\link[=ptr_server]{ptr_server()}}.
}
\details{
Because the panel includes a \code{shinyWidgets::pickerInput()} (the layer
selector) and the Bootstrap grid, it must be rendered inside a
Bootstrap page that also carries the \code{.ptr-app} theme scope and the
asset bundle. Don't assemble that scaffolding by hand: wrap your
composed pieces in \code{\link[=ptr_ui_page]{ptr_ui_page()}}, which \emph{is} the Bootstrap page and
owns the single \code{.ptr-app} scope + the (deduped) assets. For a
\code{navbarPage} or bslib root (which \code{ptr_ui_page()} does not cover) see
\code{vignette("ggpaintr-tutorial")}.

For finer control still — placing individual placeholder widgets
independently rather than the whole panel — register a custom placeholder
type; see \code{\link[=ptr_define_placeholder_value]{ptr_define_placeholder_value()}}.
}
\examples{
# Expression form (primary): an unquoted ggplot call.
ptr_ui_controls(
  ggplot(mtcars, aes(x = ppVar, y = ppVar)) + geom_point(),
  id = "p"
)
# String form (fallback): equivalent.
ptr_ui_controls(
  "ggplot(mtcars, aes(x = ppVar, y = ppVar)) + geom_point()",
  id = "p"
)
}
\seealso{
\code{\link[=ptr_ui_page]{ptr_ui_page()}}, \code{\link[=ptr_ui_assets]{ptr_ui_assets()}}, \code{\link[=ptr_ui_plot]{ptr_ui_plot()}},
\code{\link[=ptr_ui_code]{ptr_ui_code()}}, \code{\link[=ptr_shared]{ptr_shared()}}, \code{\link[=ptr_server]{ptr_server()}}
}
