% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/UserFacingCoreFunctions.R
\name{add_shape_plus}
\alias{add_shape_plus}
\title{Add a custom shape for geom_point_plus()}
\usage{
add_shape_plus(name = NULL, shape = NULL, overwrite = FALSE, ...)
}
\arguments{
\item{name}{A single character string giving the name of the new shape.}

\item{shape}{A data frame with columns \code{x}, \code{y}, and \code{piece}.}

\item{overwrite}{Logical. If \code{FALSE}, the default, an error is returned
when \code{name} already exists in the shape registry. If \code{TRUE}, the
existing shape is replaced with the newly provided shape. Useful if, e.g.,
you'd like to scale an existing shape up or down in size.}

\item{...}{Additional arguments. Partial argument matching is supported for
friendly UX.}
}
\value{
Invisibly returns the registered shape name.
}
\description{
Registers a custom point shape for use with \code{geom_point_plus()}.
Custom shapes are defined by a data frame of connected polygon coordinates
and, once validated, are stored in a session-level shape registry.
}
\details{
A shape must be supplied as a data frame with columns \code{x}, \code{y},
and \code{piece}. The \code{x} and \code{y} columns define the vertices of
the shape, centered around \code{0, 0}. Coordinates should generally be
scaled to about \code{+/-0.4} to match the scaling of built-in point shapes.
The \code{piece} column identifies separate polygon pieces within the same
shape to generate "holes," as appropriate.

For inspiration and to model inputs, see \code{ggplotplus_shapes_list} for the
structure of the built-in point shapes.
}
\examples{
test_star = data.frame(
  x = c(0.000,  0.118,  0.380,  0.190,  0.235,
        0.000, -0.235, -0.190, -0.380, -0.118),
  y = c(0.400,  0.124,  0.124, -0.047, -0.324,
       -0.153, -0.324, -0.047,  0.124,  0.124),
  piece = 1
)

add_shape_plus("test_star", test_star)

}
