% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/read_xlsx.R
\name{sheet_add_drawing}
\alias{sheet_add_drawing}
\title{Add a drawing to an Excel sheet}
\usage{
sheet_add_drawing(x, value, sheet, ...)
}
\arguments{
\item{x}{rxlsx object created by \code{\link[=read_xlsx]{read_xlsx()}}}

\item{value}{object to add (dispatched to the appropriate method)}

\item{sheet}{sheet name (must already exist, see \code{\link[=add_sheet]{add_sheet()}})}

\item{...}{method-specific arguments. Common across \code{external_img}
and \code{gg} methods: \code{left} / \code{top} (fixed-position top-left in
inches, default \verb{(1, 1)}), \code{width} / \code{height} (size in inches),
\code{anchor} (cell reference like \code{"B2"} or \code{"B2:H20"}, see
description), \code{edit_as} (one of \code{"twoCell"}, \code{"oneCell"},
\code{"absolute"}; how Excel treats the drawing when rows/columns are
resized — only meaningful with a cell range \code{anchor}). The \code{gg}
method also accepts \code{res} (ppi, default 300), \code{alt_text}
(auto-detected via \code{ggplot2::get_alt_text()} if empty) and
\code{scale} (passed to \code{\link[ragg:agg_png]{ragg::agg_png()}}).}
}
\value{
the rxlsx object (invisibly)
}
\description{
Add a graphical element into a sheet of an xlsx workbook.
This is a generic function dispatching on \code{value}. Supported inputs
include:
\itemize{
\item \code{\link[=external_img]{external_img()}}: an image file (PNG, JPEG, GIF, ...) copied into
the workbook and placed on the sheet.
\item \code{gg}: a ggplot object rendered to PNG via \code{ragg::agg_png()} and
embedded via the \code{external_img} path. Extra arguments: \code{res}
(default 300 ppi), \code{alt_text} (auto-detected via
\code{ggplot2::get_alt_text()} when empty), \code{scale} (same semantics as
\code{ggplot2::ggsave()}).
}

The drawing can be positioned in three ways, matching Excel's own
"Format Picture" options:
\itemize{
\item Fixed position (default): pass \code{left} / \code{top} and
\code{width} / \code{height} in inches. The drawing stays put when rows or
columns are inserted/resized.
\item Move and size with cells (Excel's default): pass
\code{anchor = "B2:H20"} (a cell range). The drawing spans those two
cells and follows them.
\item Move but don't size with cells: pass \code{anchor = "B2"}
(a single cell). The drawing anchors to that cell, keeping the
size set by \code{width} / \code{height}.
}

Additional methods for \code{ms_chart} and \code{dml} are provided by the
extension packages 'mschart' and 'rvg'.

Use \code{\link[=sheet_write_data]{sheet_write_data()}} to write data into the sheet before or
after adding a drawing.
}
\examples{
img <- system.file("extdata", "example.png", package = "officer")
if (nzchar(img) && file.exists(img)) {
  x <- read_xlsx()
  x <- add_sheet(x, label = "pics")
  x <- sheet_add_drawing(
    x, sheet = "pics",
    value = external_img(img, width = 2, height = 2)
  )
  print(x, target = tempfile(fileext = ".xlsx"))
}

if (requireNamespace("ggplot2", quietly = TRUE)) {
  gg <- ggplot2::ggplot(iris, ggplot2::aes(Sepal.Length, Sepal.Width)) +
    ggplot2::geom_point()
  x <- read_xlsx()
  x <- add_sheet(x, label = "plots")
  x <- sheet_add_drawing(x, value = gg, sheet = "plots",
                         width = 4, height = 3)
  print(x, target = tempfile(fileext = ".xlsx"))
}
}
\seealso{
\code{\link[=read_xlsx]{read_xlsx()}}, \code{\link[=add_sheet]{add_sheet()}}, \code{\link[=sheet_write_data]{sheet_write_data()}}
}
