gridtext/ 0000755 0001762 0000144 00000000000 13764504772 012123 5 ustar ligges users gridtext/NAMESPACE 0000644 0001762 0000144 00000001106 13764206777 013344 0 ustar ligges users # Generated by roxygen2: do not edit by hand
S3method(ascentDetails,richtext_grob)
S3method(ascentDetails,textbox_grob)
S3method(descentDetails,richtext_grob)
S3method(descentDetails,textbox_grob)
S3method(heightDetails,richtext_grob)
S3method(heightDetails,textbox_grob)
S3method(makeContent,textbox_grob)
S3method(makeContext,textbox_grob)
S3method(widthDetails,richtext_grob)
S3method(widthDetails,textbox_grob)
export(richtext_grob)
export(textbox_grob)
import(grid)
import(rlang)
importFrom(Rcpp,sourceCpp)
importFrom(xml2,read_html)
useDynLib(gridtext, .registration = TRUE)
gridtext/LICENSE 0000644 0001762 0000144 00000000054 13610076272 013114 0 ustar ligges users YEAR: 2020
COPYRIGHT HOLDER: Claus O. Wilke
gridtext/README.md 0000644 0001762 0000144 00000015766 13760022324 013401 0 ustar ligges users
gridtext
========
[](https://github.com/wilkelab/gridtext/actions)
[](https://codecov.io/github/wilkelab/gridtext?branch=master)
[](https://cran.r-project.org/package=gridtext)
[](https://www.tidyverse.org/lifecycle/#maturing)
Improved text rendering support for grid graphics in R.
Installation
------------
You can install the current release from CRAN with `install.packages()`:
install.packages("gridtext")
To install the latest development version of this package, please run
the following line in your R console:
remotes::install_github("wilkelab/gridtext")
Examples
--------
The gridtext package provides two new grobs, `richtext_grob()` and
`textbox_grob()`, which support drawing of formatted text labels and
formatted text boxes, respectively. Both grobs understand an extremely
limited subset of Markdown, HTML, and CSS directives. The idea is to
provide a minimally useful subset of features. These currently include
italics, bold, super- and subscript, as well as changing text color,
font, and font size via inline CSS. Extremely limited support for images
is also provided.
Note that all text rendering is performed through a custom-built
rendering pipeline that is part of the gridtext package. This approach
has several advantages, including minimal dependencies, good
performance, and compatibility with all R graphics devices (to the
extent that the graphics devices support the fonts you want to use). The
downside of this approach is the severely limited feature set. Don’t
expect this package to support the fancy CSS and javascript tricks
you’re used to when designing web pages.
### Richtext grob
The function `richtext_grob()` serves as a replacement for `textGrob()`.
It is vectorized and can draw multiple text labels with one call. Labels
can be drawn with padding, margins, and at arbitrary angles. Markdown
and HTML parsing is turned on by default.
library(grid)
library(gridtext)
text <- c(
"Some text **in bold.**",
"Linebreaks
Linebreaks
Linebreaks",
"*x*2 + 5*x* + *C**i*",
"Some blue text **in bold.**
And *italics text.*
And some large text."
)
x <- c(.2, .1, .7, .9)
y <- c(.8, .4, .1, .5)
rot <- c(0, 0, 45, -45)
gp = gpar(
col = c("black", "red"),
fontfamily = c("Palatino", "Courier", "Times", "Helvetica")
)
box_gp = gpar(
col = "black", fill = c(NA, "cornsilk", "lightblue1", NA),
lty = c(0, 1, 1, 1)
)
hjust <- c(0.5, 0, 0, 1)
vjust <- c(0.5, 1, 0, 0.5)
grid.newpage()
g <- richtext_grob(
text, x, y, hjust = hjust, vjust = vjust, rot = rot,
padding = unit(c(6, 6, 4, 6), "pt"),
r = unit(c(0, 2, 4, 8), "pt"),
gp = gp, box_gp = box_gp
)
grid.draw(g)
grid.points(x, y, default.units = "npc", pch = 19, size = unit(5, "pt"))

The boxes around text labels can be set to have matching widths and/or
heights, and alignment of text inside the box (specified via `hjust` and
`vjust`) is separate from alignment of the box relative to a reference
point (specified via `box_hjust` and `box_vjust`).
text <- c("January", "February", "March", "April", "May")
x <- (1:5)/6 + 1/24
y <- rep(0.8, 5)
g <- richtext_grob(
text, x, y, halign = 0, hjust = 1,
rot = 45,
padding = unit(c(3, 6, 1, 3), "pt"),
r = unit(4, "pt"),
align_widths = TRUE,
box_gp = gpar(col = "black", fill = "cornsilk")
)
grid.newpage()
grid.draw(g)
grid.points(x, y, default.units = "npc", pch = 19, size = unit(5, "pt"))

Basic support for images is available as well. As of now, images will
always be vertically aligned with the baseline of the text.
grid.newpage()
img_src <- system.file("extdata", "Rlogo.png", package = "gridtext")
text <- glue::glue("Image with native aspect ratio:
And some more text.")
grid.draw(richtext_grob(text, x = 0.9, y = 0.7, hjust = 1))
text <- glue::glue("Image with forced size:
And some more text.")
grid.draw(richtext_grob(text, x = 0.9, y = 0.3, hjust = 1))

### Textbox grob
The function `textbox_grob()` is intended to render multi-line text
labels that require automatic word wrapping. It is similar to
`richtext_grob()`, but there are a few important differences. First,
while `richtext_grob()` is vectorized, `textbox_grob()` is not. It can
draw only a single text box at a time. Second, `textbox_grob()` doesn’t
support rendering the text box at arbitrary angles. Only four different
orientations are supported, corresponding to a rotation by 0, 90, 180,
and 270 degrees.
g <- textbox_grob(
"**The quick brown fox jumps over the lazy dog.**
The quick brown fox jumps over the lazy dog.
The **quick brown fox** jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.",
x = unit(0.5, "npc"), y = unit(0.7, "npc"),
gp = gpar(fontsize = 15),
box_gp = gpar(col = "black", fill = "lightcyan1"),
r = unit(5, "pt"),
padding = unit(c(10, 10, 10, 10), "pt"),
margin = unit(c(0, 10, 0, 10), "pt")
)
grid.newpage()
grid.draw(g)

The alignment parameters `hjust`, `vjust`, `halign`, and `valign`
function just like they do in `richtext_grob()`.
g <- textbox_grob(
"**The quick brown fox jumps over the lazy dog.**
The quick brown fox jumps over the lazy dog.
The **quick brown fox** jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.",
x = unit(0.2, "npc"), y = unit(0.5, "npc"),
hjust = 0.5, vjust = 1, halign = 1,
gp = gpar(fontsize = 15),
box_gp = gpar(col = "black", fill = "lightcyan1"),
r = unit(5, "pt"),
padding = unit(c(10, 10, 10, 10), "pt"),
margin = unit(c(0, 10, 0, 10), "pt"),
orientation = "left-rotated"
)
grid.newpage()
grid.draw(g)

Acknowledgments
---------------
This project is receiving [financial
support](https://www.r-consortium.org/projects/awarded-projects) from
the [R consortium.](https://www.r-consortium.org)
gridtext/man/ 0000755 0001762 0000144 00000000000 13604245316 012663 5 ustar ligges users gridtext/man/gridtext.Rd 0000644 0001762 0000144 00000000671 13604245154 015010 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gridtext.R
\docType{package}
\name{gridtext}
\alias{gridtext}
\title{Improved text rendering support for grid graphics}
\description{
The gridtext package provides two new grobs, \code{\link[=richtext_grob]{richtext_grob()}} and
\code{\link[=textbox_grob]{textbox_grob()}}, which support drawing of formatted text labels and
formatted text boxes, respectively.
}
gridtext/man/textbox_grob.Rd 0000644 0001762 0000144 00000016330 13610075065 015662 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/textbox-grob.R
\name{textbox_grob}
\alias{textbox_grob}
\title{Draw formatted multi-line text with word wrap}
\usage{
textbox_grob(
text,
x = NULL,
y = NULL,
width = unit(1, "npc"),
height = NULL,
minwidth = NULL,
maxwidth = NULL,
minheight = NULL,
maxheight = NULL,
hjust = 0.5,
vjust = 0.5,
halign = 0,
valign = 1,
default.units = "npc",
margin = unit(c(0, 0, 0, 0), "pt"),
padding = unit(c(0, 0, 0, 0), "pt"),
r = unit(0, "pt"),
orientation = c("upright", "left-rotated", "right-rotated", "inverted"),
name = NULL,
gp = gpar(),
box_gp = gpar(col = NA),
vp = NULL,
use_markdown = TRUE
)
}
\arguments{
\item{text}{Character vector containing Markdown/HTML string to draw.}
\item{x, y}{Unit objects specifying the location of the reference point.
If set to \code{NULL} (the default), these values are chosen based on the
values of \code{hjust} and \code{vjust} such that the box is appropriately
justified in the enclosing viewport.}
\item{width, height}{Unit objects specifying width and height of the
grob. A value of \code{NULL} means take up exactly the space necessary
to render all content. Use a value of \code{unit(1, "npc")} to have the
box take up all available space.}
\item{minwidth, minheight, maxwidth, maxheight}{Min and max values for
width and height. Set to \code{NULL} to impose neither a minimum nor
a maximum. Note: \code{minheight} and \code{maxheight} do not work if \code{width = NULL}.}
\item{hjust, vjust}{Numerical values specifying the justification
of the text box relative to the reference point defined by \code{x} and \code{y}. These
justification parameters are specified in the internal reference frame of
the text box, so that, for example, \code{hjust} adjusts the vertical
justification when the text box is left- or right-rotated.}
\item{halign, valign}{Numerical values specifying the justification of the text
inside the text box.}
\item{default.units}{Units of \code{x}, \code{y}, \code{width}, \code{height}, \code{minwidth},
\code{minheight}, \code{maxwidth}, \code{maxheight} if these are provided only as
numerical values.}
\item{margin, padding}{Unit vectors of four elements each indicating the
margin and padding around each text label in the order top, right,
bottom, left. Margins are drawn outside the enclosing box (if any),
and padding is drawn inside. To avoid rendering artifacts, it is best
to specify these values in absolute units (such as points, mm, or inch)
rather than in relative units (such as npc).}
\item{r}{The radius of the rounded corners. To avoid rendering artifacts,
it is best to specify this in absolute units (such as points, mm, or inch)
rather than in relative units (such as npc).}
\item{orientation}{Orientation of the box. Allowed values are \code{"upright"},
\code{"left-rotated"}, \code{"right-rotated"}, and \code{"inverted"}, corresponding to
a rotation by 0, 90, 270, and 180 degrees counter-clockwise, respectively.}
\item{name}{Name of the grob.}
\item{gp}{Other graphical parameters for drawing.}
\item{box_gp}{Graphical parameters for the enclosing box around each text label.}
\item{vp}{Viewport.}
\item{use_markdown}{Should the \code{text} input be treated as markdown?}
}
\value{
A grid \code{\link{grob}} that represents the formatted text.
}
\description{
The function \code{textbox_grob()} is intended to render multi-line text
labels that require automatic word wrapping. It is similar to
\code{\link[=richtext_grob]{richtext_grob()}}, but there are a few important differences. First,
while \code{\link[=richtext_grob]{richtext_grob()}} is vectorized, \code{textbox_grob()} is not. It
can draw only a single text box at a time. Second, \code{textbox_grob()}
doesn't support rendering the text box at arbitrary angles. Only
four different orientations are supported, corresponding to a
rotation by 0, 90, 180, and 270 degrees.
}
\examples{
library(grid)
g <- textbox_grob(
"**The quick brown fox jumps over the lazy dog.**
The quick brown fox jumps over the lazy dog.
The **quick brown fox** jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.",
x = unit(0.5, "npc"), y = unit(0.7, "npc"), halign = 0, valign = 1,
gp = gpar(fontsize = 15),
box_gp = gpar(col = "black", fill = "lightcyan1"),
r = unit(5, "pt"),
padding = unit(c(10, 10, 10, 10), "pt"),
margin = unit(c(0, 10, 0, 10), "pt")
)
grid.newpage()
grid.draw(g)
# internal vs. external alignment
g1 <- textbox_grob(
"The quick brown fox jumps over the lazy dog.",
hjust = 0, vjust = 1, halign = 0, valign = 1,
width = unit(1.5, "inch"), height = unit(1.5, "inch"),
box_gp = gpar(col = "black", fill = "cornsilk"),
padding = unit(c(2, 2, 2, 2), "pt"),
margin = unit(c(5, 5, 5, 5), "pt")
)
g2 <- textbox_grob(
"The quick brown fox jumps over the lazy dog.",
hjust = 1, vjust = 1, halign = 0.5, valign = 0.5,
width = unit(1.5, "inch"), height = unit(1.5, "inch"),
box_gp = gpar(col = "black", fill = "cornsilk"),
padding = unit(c(2, 2, 2, 2), "pt"),
margin = unit(c(5, 5, 5, 5), "pt")
)
g3 <- textbox_grob(
"The quick brown fox jumps over the lazy dog.",
hjust = 0, vjust = 0, halign = 1, valign = 1,
width = unit(1.5, "inch"), height = unit(1.5, "inch"),
box_gp = gpar(col = "black", fill = "cornsilk"),
padding = unit(c(2, 2, 2, 2), "pt"),
margin = unit(c(5, 5, 5, 5), "pt")
)
g4 <- textbox_grob(
"The quick brown fox jumps over the lazy dog.",
hjust = 1, vjust = 0, halign = 0, valign = 0,
width = unit(1.5, "inch"), height = unit(1.5, "inch"),
box_gp = gpar(col = "black", fill = "cornsilk"),
padding = unit(c(2, 2, 2, 2), "pt"),
margin = unit(c(5, 5, 5, 5), "pt")
)
grid.newpage()
grid.draw(g1)
grid.draw(g2)
grid.draw(g3)
grid.draw(g4)
# internal vs. external alignment, with rotated boxes
g1 <- textbox_grob(
"The quick brown fox jumps over the lazy dog.",
hjust = 1, vjust = 1, halign = 0, valign = 1,
width = unit(1.5, "inch"), height = unit(1.5, "inch"),
orientation = "left-rotated",
box_gp = gpar(col = "black", fill = "cornsilk"),
padding = unit(c(2, 2, 2, 2), "pt"),
margin = unit(c(5, 5, 5, 5), "pt")
)
g2 <- textbox_grob(
"The quick brown fox jumps over the lazy dog.",
hjust = 0, vjust = 1, halign = 0.5, valign = 0.5,
width = unit(1.5, "inch"), height = unit(1.5, "inch"),
orientation = "right-rotated",
box_gp = gpar(col = "black", fill = "cornsilk"),
padding = unit(c(2, 2, 2, 2), "pt"),
margin = unit(c(5, 5, 5, 5), "pt")
)
g3 <- textbox_grob(
"The quick brown fox jumps over the lazy dog.",
hjust = 1, vjust = 1, halign = 1, valign = 1,
width = unit(1.5, "inch"), height = unit(1.5, "inch"),
orientation = "inverted",
box_gp = gpar(col = "black", fill = "cornsilk"),
padding = unit(c(2, 2, 2, 2), "pt"),
margin = unit(c(5, 5, 5, 5), "pt")
)
g4 <- textbox_grob(
"The quick brown fox jumps over the lazy dog.",
hjust = 1, vjust = 0, halign = 0, valign = 0,
width = unit(1.5, "inch"), height = unit(1.5, "inch"),
orientation = "upright",
box_gp = gpar(col = "black", fill = "cornsilk"),
padding = unit(c(2, 2, 2, 2), "pt"),
margin = unit(c(5, 5, 5, 5), "pt")
)
grid.newpage()
grid.draw(g1)
grid.draw(g2)
grid.draw(g3)
grid.draw(g4)
}
\seealso{
\code{\link[=richtext_grob]{richtext_grob()}}
}
gridtext/man/figures/ 0000755 0001762 0000144 00000000000 13760022324 014322 5 ustar ligges users gridtext/man/figures/README-unnamed-chunk-7-1.png 0000644 0001762 0000144 00000103323 13760022323 021023 0 ustar ligges users PNG
IHDR z4 iCCPkCGColorSpaceGenericRGB 8U]hU>sg#$Sl4t?
%
V46nI6"dΘ83OEP|1Ŀ (>/
% (>P苦;3ie|{g蹪X-2s=+WQ+]L6Ow[C{_F qbUvz?Zb1@/zcs>~if,ӈUSjF1_Mjbuݠpamhmçϙ>a\+5%QKFkm}ۖ?ޚD\!~6,-7SثŜvķ5Z;[rmS5{yDyH}r9|-ăFAJjI.[/]mK7KRDrYQO-Q||6
(0
MXd(@h2_f<:_δ*d>e\c?~,7?& ك^2Iq2"y