1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/flextable.R
\name{set_caption}
\alias{set_caption}
\title{Set Caption}
\usage{
set_caption(
x,
caption = NULL,
autonum = NULL,
word_stylename = "Table Caption",
style = word_stylename,
fp_p = NULL,
align_with_table = TRUE,
html_classes = NULL,
html_escape = TRUE
)
}
\arguments{
\item{x}{flextable object}
\item{caption}{caption value. The caption can be either a string either
a call to \code{\link[=as_paragraph]{as_paragraph()}}. In the latter case, users are free to format
the caption with colors, italic fonts, also mixed with images or
equations. Note that Quarto does not allow the use of this feature.
Caption as a string does not support 'Markdown' syntax. If you want to
add a bold text in the caption, use \code{as_paragraph('a ', as_b('bold'), ' text')}
when providing caption.}
\item{autonum}{an autonum representation. See \code{\link[officer:run_autonum]{officer::run_autonum()}}.
This has an effect only when the output is "Word" (in which case the object
is used to define the Word auto-numbering), "html" and "pdf" (in which case only
the bookmark identifier will be used). If used, the caption is preceded
by an auto-number sequence.}
\item{word_stylename, style}{'Word' style name to associate with caption paragraph. These names are available with
function \code{\link[officer:styles_info]{officer::styles_info()}} when output is Word. Argument \code{style}
is deprecated in favor of \code{word_stylename}. If the caption is defined with
\code{as_paragraph()}, some of the formattings of the paragraph style will be
replaced by the formattings associated with the chunks (such as the font).}
\item{fp_p}{paragraph formatting properties associated with the caption, see \code{\link[=fp_par]{fp_par()}}.
It applies when possible, i.e. in HTML and 'Word' but not with bookdown.}
\item{align_with_table}{if TRUE, caption is aligned as the flextable, if FALSE,
\code{fp_p} will not be updated and alignement is as defined with \code{fp_p}.
It applies when possible, i.e. in HTML and 'Word' but not with bookdown.}
\item{html_classes}{css class(es) to apply to associate with caption paragraph
when output is 'Word'.}
\item{html_escape}{should HTML entities be escaped so that it can be safely
included as text or an attribute value within an HTML document.}
}
\description{
Set caption value in a flextable. The function
can also be used to define formattings that will be applied
if possible to Word and HTML outputs.
\itemize{
\item The caption will be associated with a paragraph style when
the output is Word. It can also be numbered as a auto-numbered
Word computed value.
\item The PowerPoint format ignores captions. PowerPoint documents are not
structured and do not behave as HTML documents and paginated documents
(word, pdf), and it's not possible to know where we should create
a shape to contain the caption (technically it can't be in the
PowerPoint shape containing the table).
}
When working with 'R Markdown' or 'Quarto', the caption settings
defined with \code{set_caption()} will be prioritized over knitr chunk options.
Caption value can be a single string or the result to a call to
\code{\link[=as_paragraph]{as_paragraph()}}. With the latter, the caption is made of
formatted chunks whereas with the former, caption will not be
associated with any formatting.
}
\details{
The values defined by \code{set_caption()} will be preferred when possible, i.e. the
caption ID, the associated paragraph style, etc. Why specify "where possible"?
Because the principles differ from tool to tool. Here is what we have noticed
and tried to respect (if you think we are wrong, let us know):
\itemize{
\item Word and HTML documents made with 'rmarkdown', i.e. with \code{rmarkdown::word_document()}
and \code{rmarkdown::html_document()} are not supposed to have numbered and cross-referenced captions.
\item PDF documents made with 'rmarkdown' \code{rmarkdown::pdf_document()} automatically add numbers
before the caption.
\item Word and HTML documents made with 'bookdown' are supposed to have numbered and
cross-referenced captions. This is achieved by 'bookdown' but for technical reasons,
the caption must not be defined in an HTML or XML block. So with flextable we lose
the ability to format the caption content; surprisingly this is not the case with PDF.
\item HTML and PDF documents created with Quarto will manage captions and cross-references
differently; Quarto will replace captions with \code{tbl-cap} and \code{label} values.
\item Word documents made with Quarto are another specific case, Quarto does not
inject captions from the \code{tbl-cap} and \code{label} values. This is a temporary
situation that should evolve later. flextable' will evolve according to the
evolution of Quarto.
}
Using \code{\link[=body_add_flextable]{body_add_flextable()}} enable all options specified with \code{set_caption()}.
}
\section{R Markdown}{
flextable captions can be defined from R Markdown documents by using
\code{knitr::opts_chunk$set()}. User don't always have to call \code{set_caption()}
to set a caption, he can use knitr chunk options instead. A typical call
would be:
\if{html}{\out{<div class="sourceCode">}}\preformatted{```\{r\}
#| tab.id: bookmark_id
#| tab.cap: caption text
flextable(head(cars))
```
}\if{html}{\out{</div>}}
\code{tab.id} is the caption id or bookmark, \code{tab.cap} is the caption
text. There are many options that can replace \code{set_caption()}
features. The following knitr chunk options are available:\tabular{lcc}{
\strong{label} \tab \strong{name} \tab \strong{value} \cr
Word stylename to use for table captions. \tab tab.cap.style \tab NULL \cr
caption id/bookmark \tab tab.id \tab NULL \cr
caption \tab tab.cap \tab NULL \cr
display table caption on top of the table or not \tab tab.topcaption \tab TRUE \cr
caption table sequence identifier. \tab tab.lp \tab "tab:" \cr
prefix for numbering chunk (default to "Table "). \tab tab.cap.pre \tab Table \cr
suffix for numbering chunk (default to ": "). \tab tab.cap.sep \tab " :" \cr
title number depth \tab tab.cap.tnd \tab 0 \cr
separator to use between title number and table number. \tab tab.cap.tns \tab "-" \cr
caption prefix formatting properties \tab tab.cap.fp_text \tab fp_text_lite(bold = TRUE) \cr
}
See \link{knit_print.flextable} for more details.
}
\section{Formatting the caption}{
You can build your caption with \code{as_paragraph()}.
This is recommended if your captions need complex content. The caption is build
with a paragraph made of chunks (for example, a red bold text + Arial italic
text).
The user will then have the ability to format text and to add images
and equations. If no format is specified (using \code{"a string"}
or \code{as_chunk("a string")}), \code{\link[=fp_text_default]{fp_text_default()}} is used to define
font settings (font family, bold, italic, color, etc...).
The default values can be changed with set_flextable_defaults().
It is recommended to explicitly use \code{as_chunk()}.
The counterpart is that the style properties of the caption will
not take precedence over those of the formatted elements. You will
have to specify the font to use:
\if{html}{\out{<div class="sourceCode">}}\preformatted{ftab <- flextable(head(cars)) \%>\%
set_caption(
as_paragraph(
as_chunk("caption", props = fp_text_default(font.family = "Cambria"))
), word_stylename = "Table Caption")
print(ftab, preview = "docx")
}\if{html}{\out{</div>}}
}
\section{Using 'Quarto'}{
'Quarto' manage captions and cross-references instead of flextable. That's why
\code{set_caption()} is not that useful in a 'Quarto' document except for Word documents
where 'Quarto' does not manage captions yet (when output is raw xml which is the
case for flextable).
knitr options are almost the same than those detailled in the R Markdown section (see upper),
but be aware that 'Quarto' manage captions and it can be overwrite what has
been defined by flextable. See Quarto documentation for more information.
}
\examples{
ftab <- flextable( head( iris ) )
ftab <- set_caption(ftab, "my caption")
ftab
library(officer)
autonum <- run_autonum(seq_id = "tab", bkm = "mtcars")
ftab <- flextable( head( mtcars ) )
ftab <- set_caption(ftab, caption = "mtcars data", autonum = autonum)
ftab
}
\seealso{
\code{\link[=flextable]{flextable()}}
}
|
