% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/xl_chart_parts.R
\name{xl_chart_labels}
\alias{xl_chart_labels}
\alias{xl_chart_label}
\title{Data labels on a chart series}
\usage{
xl_chart_labels(
  show_value = NA,
  show_name = NA,
  show_category = NA,
  show_percentage = NA,
  show_legend_key = NA,
  num_format = NULL,
  position = NULL,
  separator = NULL,
  format = NULL,
  leader_lines = NA,
  custom = NULL
)

xl_chart_label(value = NULL, hide = NA, format = NULL)
}
\arguments{
\item{show_value, show_name, show_category, show_percentage}{What each label
holds: the point's value, the series name, the category, and the value as
a percentage of the series.  Naming any of them means the label holds
exactly those, so `show_percentage = TRUE` alone gives a percentage and
nothing else; naming none of them leaves Excel's default, the value.
Percentages are meaningful on pie and doughnut charts.}

\item{show_legend_key}{Print the series' legend swatch in each label.}

\item{num_format}{A number format for the labels, as an Excel format string
or an [xl_num_format()].}

\item{position}{Where the label sits relative to its point; see the
description for which chart types allow which.}

\item{separator}{What joins the parts of a label when it holds more than
one: `"comma"`, `"semicolon"`, `"period"`, `"newline"` or `"space"`.}

\item{format}{An [xl_format()] styling the labels.  A label is a shape with
text in it, so all of [xl_font()], [xl_border()] and [xl_fill()] apply.}

\item{leader_lines}{Draw a line from a label back to its point.  Excel only
shows one once the label has been dragged away from the point.}

\item{custom}{A list of [xl_chart_label()]s, one per point in order, giving
individual labels their own text, styling, or `hide = TRUE`.  `NULL` in
the list leaves that point's label alone.}

\item{value}{The label's text.  A string beginning with `"="` is a formula,
so `"=Sheet1!$A$1"` takes the text from a cell.}

\item{hide}{Remove this point's label, leaving the others.}
}
\value{
An `xl_chart_labels` object.
}
\description{
`xl_chart_labels()` prints the numbers next to the points that carry them.
With no arguments it shows the value of each point, which is Excel's own
default.

`xl_chart_label()` describes one label, for `custom`: a label can be given
its own text or hidden, one point at a time.

Excel allows different label positions for different chart types, and drops
one that does not apply.  The table is in libxlsxwriter's header and is
enforced here: `"center"` is allowed everywhere, `"right"`, `"left"`,
`"above"` and `"below"` on line and scatter charts, `"inside_base"` on bar
and column, `"inside_end"` and `"outside_end"` on bar, column, pie and
doughnut, and `"best_fit"` on pie and doughnut.
}
\examples{
xl_chart_labels()
xl_chart_labels(show_category = TRUE, show_percentage = TRUE,
                separator = "newline", position = "outside_end")
}
\seealso{
[xl_chart_series]

Other images and charts:
\code{\link[=xl_chart]{xl_chart()}},
\code{\link[=xl_chart_axis]{xl_chart_axis()}},
\code{\link[=xl_chart_error_bars]{xl_chart_error_bars()}},
\code{\link[=xl_chart_legend]{xl_chart_legend()}},
\code{\link[=xl_chart_marker]{xl_chart_marker()}},
\code{\link[=xl_chart_series]{xl_chart_series()}},
\code{\link[=xl_chart_table]{xl_chart_table()}},
\code{\link[=xl_chart_trendline]{xl_chart_trendline()}},
\code{\link[=xl_chartsheet]{xl_chartsheet()}},
\code{\link[=xl_image]{xl_image()}}
}
\concept{images and charts}
