% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rtf.R
\name{rtf_add}
\alias{rtf_add}
\alias{rtf_add.block_section}
\alias{rtf_add.character}
\alias{rtf_add.factor}
\alias{rtf_add.double}
\alias{rtf_add.fpar}
\alias{rtf_add.block_list}
\alias{rtf_add.block_toc}
\alias{rtf_add.gg}
\alias{rtf_add.plot_instr}
\title{Add content into an RTF document}
\usage{
rtf_add(x, value, ...)

\method{rtf_add}{block_section}(x, value, ...)

\method{rtf_add}{character}(x, value, style = NULL, ...)

\method{rtf_add}{factor}(x, value, style = NULL, ...)

\method{rtf_add}{double}(x, value, formatter = formatC, style = NULL, ...)

\method{rtf_add}{fpar}(x, value, style = NULL, ...)

\method{rtf_add}{block_list}(x, value, style = NULL, ...)

\method{rtf_add}{block_toc}(x, value, ...)

\method{rtf_add}{gg}(
  x,
  value,
  width = 6,
  height = 5,
  res = 300,
  scale = 1,
  ppr = fp_par(text.align = "center"),
  ...
)

\method{rtf_add}{plot_instr}(
  x,
  value,
  width = 6,
  height = 5,
  res = 300,
  scale = 1,
  ppr = fp_par(text.align = "center"),
  ...
)
}
\arguments{
\item{x}{rtf object, created by \code{\link[=rtf_doc]{rtf_doc()}}.}

\item{value}{object to add in the document. Supported objects
are vectors, graphics, block of formatted paragraphs. Use package
'flextable' to add tables.}

\item{...}{further arguments passed to or from other methods. When
adding a \code{ggplot} object or \link{plot_instr}, these arguments will be used
by png function. See section 'Methods' to see what arguments can be used.}

\item{style}{style identifier (\code{style_id}) of a paragraph style registered
on the document. Defaults to \code{NULL} (use the document's normal style). See
\code{\link[=rtf_set_paragraph_style]{rtf_set_paragraph_style()}} and \code{\link[=rtf_styles_info]{rtf_styles_info()}}.}

\item{formatter}{function used to format the numerical values}

\item{width}{height in inches}

\item{height}{height in inches}

\item{res}{resolution of the png image in ppi}

\item{scale}{Multiplicative scaling factor, same as in ggsave}

\item{ppr}{\code{\link[=fp_par]{fp_par()}} to apply to paragraph.}
}
\description{
This function add 'officer' objects into an RTF document.
Values are added as new paragraphs. See section 'Methods (by class)'
that list supported objects.
}
\section{Methods (by class)}{
\itemize{
\item \code{rtf_add(block_section)}: add a new section definition

\item \code{rtf_add(character)}: add characters as new paragraphs

\item \code{rtf_add(factor)}: add a factor vector as new paragraphs

\item \code{rtf_add(double)}: add a double vector as new paragraphs

\item \code{rtf_add(fpar)}: add an \code{\link[=fpar]{fpar()}}

\item \code{rtf_add(block_list)}: add an \code{\link[=block_list]{block_list()}}

\item \code{rtf_add(block_toc)}: add a \code{\link[=block_toc]{block_toc()}} (table of contents).
Word populates the TOC at open time from paragraphs styled with the
built-in heading styles (which carry an outline level). LibreOffice
will not render the TOC automatically.

\item \code{rtf_add(gg)}: add a ggplot2

\item \code{rtf_add(plot_instr)}: add a \code{\link[=plot_instr]{plot_instr()}} object

}}
\section{Section model in RTF}{

A \code{block_section} added with \code{rtf_add()} applies to the content that
\strong{follows} the call: it opens a new section whose layout (orientation,
columns, margins, headers / footers) is inherited by every paragraph,
table or graphic added afterwards, until the next \code{block_section} (or
the end of the document).

Typical pattern: declare the section, then add the content.

\if{html}{\out{<div class="sourceCode r">}}\preformatted{doc <- rtf_doc() |>
  rtf_add(block_section(prop_section(
    page_size = page_size(orient = "landscape")
  ))) |>
  rtf_add(fpar("This paragraph is in landscape orientation."))
}\if{html}{\out{</div>}}

The first section of the document is configured via the \code{def_sec}
argument of \code{\link[=rtf_doc]{rtf_doc()}} (a \link{prop_section} object, not a
\code{block_section}). It applies to every element added before the first
\code{rtf_add(block_section(...))} call.

The Word output uses the opposite model: \code{body_end_block_section()}
applies to the content that \emph{precedes} the call. See
\code{\link[=body_end_block_section]{body_end_block_section()}}.
}

\examples{
## Simple RTF example ----

library(officer)

def_text <- fp_text_lite(color = "#006699", bold = TRUE)
center_par <- fp_par(text.align = "center", padding = 3)

doc <- rtf_doc(
  normal_par = fp_par(line_spacing = 1.4, padding = 3)
)

doc <- rtf_add(
  x = doc,
  value = fpar(
    ftext("how are you?", prop = def_text),
    fp_p = fp_par(text.align = "center")
  )
)

a_paragraph <- fpar(
  ftext("Here is a date: ", prop = def_text),
  run_word_field(field = "Date \\\\@ \"MMMM d yyyy\""),
  fp_p = center_par
)
doc <- rtf_add(
  x = doc,
  value = block_list(
    a_paragraph,
    a_paragraph,
    a_paragraph
  )
)

if (require("ggplot2")) {
  gg <- gg_plot <- ggplot(data = iris) +
    geom_point(mapping = aes(Sepal.Length, Petal.Length))
  doc <- rtf_add(doc, gg, width = 3, height = 4, ppr = center_par)
}
anyplot <- plot_instr(code = {
  barplot(1:5, col = 2:6)
})
doc <- rtf_add(doc, anyplot, width = 5, height = 4, ppr = center_par)

print(doc, target = tempfile(fileext = ".rtf"))


## RTF example with sections ----

library(officer)

quick_section_header <- function(label) {
  block_list(
    fpar(
      ftext(label, fp_text_lite(bold = TRUE, color = "#006699"))
    )
  )
}

quick_section_footer <- function(label) {
  block_list(
    fpar(
      "Page ",
      run_word_field(field = "PAGE  \\\\* MERGEFORMAT")
    )
  )
}

quick_hello_world <- function(doc) {
  rtf_add(
    doc,
    fpar(
      ftext(
        "Hello World"
      ),
      fp_p = fp_par(text.align = "left")
    )
  )
}

three_cols_section <- block_section(
  prop_section(
    type = "continuous",
    section_columns = section_columns(widths = c(1.7, 1.7, 1.7), space = 0.25),
    header_default = quick_section_header("Three columns section"),
    footer_default = quick_section_footer("Three columns section")
  )
)

doc <- rtf_doc(
  def_sec = prop_section(
    header_default = quick_section_header("Default section"),
    footer_default = quick_section_footer("Default section")
  ),
  normal_par = fp_par(padding = 3)
)
doc <- rtf_add(doc, block_toc(level = 3))

doc <- rtf_add(doc, "Sections demo", style = "heading 1")
doc <- rtf_add(doc, "Default section", style = "heading 2")
doc <- quick_hello_world(doc)

if (require("ggplot2")) {
  gg_iris <- ggplot(iris, aes(Sepal.Length, Petal.Length, colour = Species)) +
    geom_point() +
    theme_minimal()
  doc <- rtf_add(doc, gg_iris, width = 4, height = 3)
}

doc <- rtf_add(doc, "Three columns", style = "heading 2")

doc <- rtf_add(doc, three_cols_section)

titles_list <- block_list(
  fpar(ftext("Left Title"), fp_p = fp_par(text.align = "left")),
  fpar(
    run_columnbreak(),
    ftext("Centered Title"),
    fp_p = fp_par(text.align = "center")
  ),
  fpar(
    run_columnbreak(),
    ftext("Right Title"),
    fp_p = fp_par(text.align = "right")
  )
)
doc <- rtf_add(doc, titles_list)
doc <- rtf_add(doc, block_section(prop_section()))
doc <- rtf_add(doc, fpar(run_linebreak()))
doc <- quick_hello_world(doc)

landscape_section <- block_section(prop_section(
  type = "nextPage",
  page_size = page_size(orient = "landscape"),
  header_default = quick_section_header("Landscape section"),
  footer_default = quick_section_footer("Landscape section")
))
doc <- rtf_add(doc, landscape_section)
doc <- rtf_add(doc, "Landscape orientation", style = "heading 2")
doc <- quick_hello_world(doc)

doc <- rtf_add(
  doc,
  block_section(
    prop_section(
      type = "nextPage",
      header_default = quick_section_header("Final section"),
      footer_default = quick_section_footer("Final section")
    )
  )
)
doc <- rtf_add(doc, "Back to portrait", style = "heading 2")
doc <- quick_hello_world(doc)
print(doc, target = tempfile(fileext = ".rtf"))
}
