props-setter: Update Graphical Properties for Selected Table Elements

Description Usage Arguments Details Value See Also Examples

Description

Update the graphical properties for selected table entries, hvrules, or blocks in a plotted table.

Usage

1
2
props(x, id=NULL, regex=NULL, setEnabled=TRUE, mustMatch=TRUE, 
    ...) <- value

Arguments

x

A pltdTable object containing a plotted table.

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 value is an element_entry or element_refmark object.)

setEnabled

Logical scalar. If TRUE then any element whose properties are updated by this function will have its enabled value set to TRUE (and thus will be displayed in a plot). enabled will not be changed for elements that are not updated. If setEnabled is FALSE, enabled is not changed for any elements.

mustMatch

Logical scalar. If TRUE, any strings in argument id that do not match an element or part ID in x will be treated as an error.

...

Additional arguments passed to grepl when regex is used to select table entries.

value

An element_entry, element_refmark, element_hvrule, or element_block object that contains the new values for graphical properties. See DETAILS.

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

 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
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

  

tablesgg documentation built on June 3, 2021, 1:06 a.m.