% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/primitive-fence.R
\name{primitive_fence}
\alias{primitive_fence}
\title{Guide primitive: fence}
\usage{
primitive_fence(
  key = "range_auto",
  rail = "none",
  angle = waiver(),
  oob = "squish",
  drop_zero = TRUE,
  pad_discrete = 0.5,
  levels_text = NULL,
  levels_post = NULL,
  levels_rail = NULL,
  theme = NULL,
  position = waiver()
)
}
\arguments{
\item{key}{A \link[=key_range]{range key} specification. See more information
in the linked topic.}

\item{rail}{A \verb{<character[1]>} giving an option for how to display fence
railing. Can be either \code{"none"} (default) to display no railings, \code{"inner"}
to draw one rail closer to the plot panel, \code{"outer"} to display one rail
farther from the plot panel, or \code{"both"} to sandwich the labels between
rails.}

\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{oob}{A method for dealing with out-of-bounds (oob) ranges. Can be one
of \code{"squish"}, \code{"censor"} or \code{"none"}.}

\item{drop_zero}{A \verb{<logical[1]>} whether to drop near-zero width ranges
(\code{TRUE}, default) or preserve them (\code{FALSE}).}

\item{pad_discrete}{A \verb{<numeric[1]>} giving the amount ranges should be
extended when given as a discrete variable. This is applied after
the \code{drop_zero} setting.}

\item{levels_text}{A list of \verb{<element_text>} objects to customise how
text appears at every level.}

\item{levels_post, levels_rail}{A list of \verb{<element_line>} objects to
customise how fence posts and rails are displayed at every level.}

\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{<PrimitiveFence>} primitive guie that can be used inside other
guides.
}
\description{
This function constructs a fence \link[=guide-primitives]{guide primitive}. The
customisation options are easier to understand if we view fence 'post' as the
vertical pieces of a real world fence, and the 'rail' as the horizontal
pieces.
}
\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
   \code{legendry.fence} \tab Both \tab \code{\link[ggplot2:element_line]{element_line()}} \tab Line segments for both 'post' and 'rail' segments \cr
   \code{legendry.fence.post} \tab Both \tab \code{\link[ggplot2:element_line]{element_line()}} \tab Line segments orthogonal to the scale \cr
   \code{legendry.fence.rail} \tab Both \tab \code{\link[ggplot2:element_line]{element_line()}} \tab Line segments parallel to the scale \cr
   \verb{axis.text.\{position\}} \tab Axis \tab \code{\link[ggplot2:element_text]{element_text()}} \tab The text labels at the fence. \cr
   \code{legend.text} \tab Legend \tab \code{\link[ggplot2:element_text]{element_text()}} \tab The text labels at the fence. \cr
}


Styling options \emph{per level} can be set in the \code{levels_post}, \code{levels_rail}
and \code{levels_text} arguments. These override theme settings.

Styling options \emph{per range} can be set in the \link[=key_range]{range key}.
The \code{line} and \code{text} prefixed properties are prioritised for the fence
and text respectively. The 'post' and 'rail' distinction does not apply
at the 'per range' settings. These override theme settings and the
'per level' 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_fence(theme = theme_guide(
  fence = element_line(),
  fence.post = element_line(),
  fence.rail = element_line(),
  text = element_text()
))
}\if{html}{\out{</div>}}
}
}
\examples{
# A standard plot
p <- ggplot(mpg, aes(interaction(drv, year), displ)) +
  geom_point()

key <- key_range_manual(c(2, 4), c(5, 6), c("A", "B"))

# Adding as secondary guides
p + guides(
  x.sec = primitive_fence(rail = "inner"),
  y.sec = primitive_fence(key = key, rail = "outer")
)
}
\seealso{
Other primitives:
\code{\link[=primitive_box]{primitive_box()}},
\code{\link[=primitive_bracket]{primitive_bracket()}},
\code{\link[=primitive_labels]{primitive_labels()}},
\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}
