% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/primitive-labels.R
\name{primitive_labels}
\alias{primitive_labels}
\title{Guide primitive: labels}
\usage{
primitive_labels(
  key = NULL,
  angle = waiver(),
  n.dodge = 1L,
  check.overlap = FALSE,
  theme = NULL,
  position = waiver()
)
}
\arguments{
\item{key}{A \link[=key_standard]{standard key} specification. See more information
in the linked topic.}

\item{angle}{A specification for the text angle. Compared to setting the \code{angle} argument
in \code{\link[ggplot2:element_text]{element_text()}}, this argument uses some
heuristics to automatically pick the \code{hjust} and \code{vjust} that you
probably want. Can be one of the following:
\itemize{
\item \code{NULL} to take angles and justification settings directly from the theme.
\item \code{\link[ggplot2:waiver]{waiver()}} to allow reasonable defaults in special
cases.
\item A \verb{<numeric[1]>} between -360 and 360 for the text angle in degrees.
}}

\item{n.dodge}{An positive \verb{<integer[1]>} setting the number of layers text
labels can occupy to avoid overlapping labels.}

\item{check.overlap}{A \verb{<logical[1]>} indicating whether to check for and
omit overlapping text. If \code{TRUE}, first, last and middle labels are
recursively prioritised in that order. If \code{FALSE}, all labels are drawn.}

\item{theme}{A \code{\link[ggplot2:theme]{<theme>}} object to style the guide individually or
differently from the plot's theme settings. The \code{theme} argument in the
guide overrides and is combined with the plot's theme.}

\item{position}{A \verb{<character[1]>} giving the location of the guide. Can be one of \code{"top"},
\code{"bottom"}, \code{"left"} or \code{"right"}.}
}
\value{
A \verb{<PrimitiveLabels>} primitive guide that can be used inside other
guides.
}
\description{
This function constructs a labels \link[=guide-primitives]{guide primitive}.
}
\details{
\subsection{Styling options}{

Below are the \link[ggplot2:theme]{theme} options that determine the styling of
this guide, which may differ depending on whether the guide is used in
an axis or in a legend context.

The possible \code{{position}} suffixes mentioned below are \code{x}, \code{x.top},
\code{x.bottom}, \code{y}, \code{y.left}, \code{y.right}. The \code{theta} and \code{r} position suffixes
in \pkg{ggplot2} are \emph{not} obeyed in \pkg{legendry}.\tabular{llll}{
   \strong{Theme setting} \tab \strong{Context} \tab \strong{Type} \tab \strong{Description} \cr
   \verb{axis.text.\{position\}} \tab Axis \tab \code{\link[ggplot2:element_text]{element_text()}} \tab The text labels. \cr
   \code{legend.text} \tab Legend \tab \code{\link[ggplot2:element_text]{element_text()}} \tab The text labels. \cr
}


Styling options \emph{per break} can be set in the \link[=key_standard]{standard key}.
The \code{text} prefixed properties are prioritised. These override theme
settings.

The context-agnostic alternative to using \code{theme()} is to use
\code{\link[=theme_guide]{theme_guide()}}:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{primitive_labels(theme = theme_guide(
  text = element_line()
))
}\if{html}{\out{</div>}}
}
}
\examples{
# A standard plot
p <- ggplot(mpg, aes(displ, hwy)) +
 geom_point()

# Adding as secondary guides
p + guides(
  x.sec = primitive_labels(),
  y.sec = primitive_labels(n.dodge = 2)
)
}
\seealso{
Other primitives:
\code{\link[=primitive_box]{primitive_box()}},
\code{\link[=primitive_bracket]{primitive_bracket()}},
\code{\link[=primitive_fence]{primitive_fence()}},
\code{\link[=primitive_line]{primitive_line()}},
\code{\link[=primitive_segments]{primitive_segments()}},
\code{\link[=primitive_spacer]{primitive_spacer()}},
\code{\link[=primitive_ticks]{primitive_ticks()}},
\code{\link[=primitive_title]{primitive_title()}}
}
\concept{primitives}
