% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/paintr-plotly.R
\name{ptr_ggplotly}
\alias{ptr_ggplotly}
\title{Build a plotly Widget From a \code{ggpaintr} Instance, Wired for Linked Selection}
\usage{
ptr_ggplotly(state, ..., source = NULL)
}
\arguments{
\item{state}{A \code{ptr_state} handle as returned by \code{\link[=ptr_server]{ptr_server()}}.}

\item{...}{Forwarded verbatim to \code{\link[plotly:ggplotly]{plotly::ggplotly()}} (e.g.
\code{tooltip = "all"}).}

\item{source}{Character scalar for plotly's \verb{source =} channel, or \code{NULL}
(default) to derive a distinct string from the instance namespace.}
}
\value{
A plain plotly htmlwidget object (inherits class \code{"plotly"}), with
\code{dragmode = "select"} set and the \code{plotly_selected} / \code{plotly_deselect}
events registered.
}
\description{
\code{ptr_ggplotly()} is the state-first counterpart to \code{\link[plotly:ggplotly]{plotly::ggplotly()}} for
the supported L3 custom-render pattern (see \code{\link[=ptr_server]{ptr_server()}}, section "Custom
render (L3)"). Call it from inside \code{\link[plotly:plotly-shiny]{plotly::renderPlotly()}} on the live
instance returned by \code{\link[=ptr_server]{ptr_server()}}: it reads the drawn plot off
\code{state$runtime()$plot}, mints a per-draw row key (the plotly \code{key}
aesthetic, on a widget-only copy of the data), sets \code{dragmode = "select"},
registers the \code{plotly_selected} / \code{plotly_deselect} events, and returns a
plain plotly object so your own plotly verbs stay composable after it.
}
\details{
The helper owns the \code{\link[shiny:req]{shiny::req()}} pre-draw guard (it raises Shiny's silent
pre-draw condition before the first draw, exactly like a bare \code{req(p)}) and
derives plotly's \verb{source =} channel from the instance namespace, so the
companion selection reader coordinates without extra wiring. The user's
drawn data is never mutated: keys are minted per draw on the widget copy
only.

plotly is an optional dependency (in \code{Suggests}). When it is not installed,
this function aborts, mirroring \code{\link[=ptr_app_bslib]{ptr_app_bslib()}}'s bslib guard.
}
\examples{
if (interactive()) {
library(shiny)
library(plotly)
f <- rlang::expr(
  ggplot(mtcars, aes(x = ppVar(wt), y = ppVar(mpg))) + geom_point()
)
ui <- ptr_ui_page(
  ptr_ui_controls(formula = f, id = "p"),
  plotly::plotlyOutput("plt")
)
server <- function(input, output, session) {
  state <- ptr_server(f, "p")
  output$plt <- plotly::renderPlotly({
    # state-first: req() guard + key minting + select wiring are internal
    ptr_ggplotly(state, tooltip = "all") |>
      plotly::layout(legend = list(orientation = "h"))
  })
}
shinyApp(ui, server)
}

}
\seealso{
\code{\link[=ptr_server]{ptr_server()}} for the L3 custom-render contract;
\code{\link[plotly:ggplotly]{plotly::ggplotly()}}.
}
