| props<- {tablesgg} | R Documentation |
Update Graphical Properties for Selected Table Elements
Description
Update the graphical properties for selected table entries, hvrules, or blocks in a plotted table.
Usage
props(x, id=NULL, regex=NULL, setEnabled=TRUE, mustMatch=TRUE,
...) <- value
Arguments
x |
A |
id |
Optional character vector of the ID's of the elements (or of table parts containing the elements) to be modified. |
regex |
Optional character string containing a regular expression. This will be
used to find table entries whose text matches the regular expression.
(Only valid when |
setEnabled |
Logical scalar. If TRUE then any element whose properties are updated by
this function will have its |
mustMatch |
Logical scalar. If TRUE, any strings in argument |
... |
Additional arguments passed to |
value |
An |
Details
There are three similar functions that can be used to modify the graphical
properties of table elements: props<-, propsa<-, and
propsd<-. They differ only in how one specifies which elements are
to be modified. props<- uses element or block ID's, or searches
the text content of entries. propsa<- uses explicit row and column
numbers within the augmented row-column grid. propsd<- uses the
values of element descriptors (as described in ?elements).
The type of elements that are updated is determined by value: if
value is an element_entry or element_refmark object
then entries are updated; if it is an element_hvrule object then
hvrules are; if it is an element_block object then blocks are. See
the documentation of those functions for the available properties. As an
example, element_entry(color="red", fontface=3, hpad=rel(0.8))
specifies that all the updated entries will be displayed in red italics,
and padding on their left and right will be reduced to 80% of the current
amount. Any graphical properties not mentioned in the call that creates
the element_* object are left unchanged.
There are two special properties: enabled and textspec (the
latter only for entries). enabled is a logical scalar. If
enabled is set to FALSE the selected elements will not be
displayed, and disabled entries/hvrules will not be allocated any space in
the plotted table. textspec is a character string, one of "plain",
"plotmath", or "markdown". If "plotmath", entry text will be treated as
an expression that allows display of mathematical symbols and notation,
including subscripts and superscripts (see ?plotmath). If
"markdown", entry text may contain markdown or HTML tags that affect the
appearance of the displayed text. (This requires the ggtext
package, and only a subset of HTML tags is supported. See the
ggtext package documentation for more information.)
element_refmark is used to add a reference mark to the selected
entries. (A reference mark is a symbol placed before or after entry text
to indicate cross-references; e.g. for footnotes.) It may also update any
of the graphical properties accepted by element_entry, except
textspec and text.
Arguments id and regex indicate which elements are to be
updated. When value indicates that table entries are to be
modified, id may specify the ID's of individual entries or the ID's
of table parts or blocks. In the latter case, all entries completely or
partially contained in the parts or blocks are selected. Thus, for
example, specifying id="table" will update every entry in the
table, while id="body" will update only entries in the table body.
Argument regex is only valid for modifying table entries;
grepl is used to identify the entries whose text matches the
regex pattern. If both id and regex are specified,
then only entries selected by both are modified.
When value indicates that hvrules are to be modified, id
should contain the ID's of individual hvrules and/or table blocks. In the
latter case, any hvrule associated with a listed block (that is, the
hvrule was defined as running along one of the sides of the block) will be
updated.
When value indicates that blocks are to be modified, id
should contain the ID's of individual table blocks.
See ?elements for the format of element ID strings.
This function overrides graphical properties in x that may have
been set by a style. Therefore the value of style_row is set to NA
for any elements whose properties are updated by this function.
Value
An object like x, with updated graphical properties for the
selected elements.
See Also
element_entry, element_refmark,
element_hvrule, element_block,
ids, propsa<-, propsd<-
Examples
ttbl <- textTable(iris2_tab, title="The iris data",
subtitle=c("Summary statistics by species",
"A second subtitle line"),
foot="sd = standard deviation")
plt <- plot(ttbl)
# Change properties of elements:
props(plt, id="body") <- element_entry(fontface=3, fill="gray85")
# This may include changing text:
props(plt, id="subtitle,2") <- element_entry(text="Properties changed by 'props<-'",
fill="gray85")
# Use property 'enabled' to control whether an element is displayed:
props(plt, id="rowhead_and_body_bottom") <- element_hvrule(enabled=FALSE)
plt
# Add reference marks to entries with abbreviation "sd":
plt <- plot(ttbl)
props(plt, regex="^sd$") <- element_refmark(mark="*", side="after")
props(plt, regex="^sd =") <- element_refmark(mark="*", side="before")
plt
# If both 'id' and 'regex' are specified only the intersection is modified:
plt <- plot(ttbl)
props(plt, regex="^sd$", id="rowblock/B/2/1") <-
element_refmark(mark="*", side="after")
props(plt, regex="^sd =") <- element_refmark(mark="*", side="before")
plt