showtext_begin {showtext}

Rendering Text for R Graphics Devices

Description

The two versions of this function are equivalent, but the "underscore" naming is preferred.

Calling this function will use showtext to render text for the current graphics device. The main advantage of showtext is that user can use any supported font file for the text rendering, and text glyphs will be converted into polygons (for vector graphics) or raster images (for bitmap and on-screen graphics), thus producing device independent output on all platforms. This function would be useful if you want to use non-standard fonts in the graphics device. The usage of this function is easy: simply open the graphics device, and "claim" that you want to use showtext by calling this function. See the Examples section for details.

Usage

showtext_begin()

showtext.begin()

Details

This package uses FreeType to load font files and render text characters. The font loading part is done by function font_add() in the sysfonts package. Users could read the help page of font_paths(), font_files() and font_add() to learn how to load a font file into R. showtext package has a built-in font file of the WenQuanYi Micro Hei family, and it will be loaded automatically, so users can use this function directly without any extra settings.

The mechanism of this function is that it can replace the text rendering functions contained in the current device. showtext will first use FreeType to analyze the outline of each character in the text, and then call some low-level drawing functions in the current device to draw the glyph. As a result, glyphs of the text will be finally converted into polygons or raster images, which means that the system where the graph is viewed does not need to install the fonts that create the graph.

Notice that this function is only effective to the current ACTIVE device. So to use this function, the device you want to work with must have already been opened (through functions like png(), pdf(), etc.).

To switch back, users can call showtext_end() to restore the original device functions. See examples below for the usage of these functions.

Author(s)

Yixuan Qiu <https://statr.me/>

See Also

showtext_opts(), showtext_auto(), showtext_end()

Examples

## Not run: 
old = setwd(tempdir())

###  Enable pdf() to draw Chinese characters nicely  ###
###  Requires the simkai.ttf font file, usually      ###
###  installed in Windows                            ###

## First, open the device
pdf("showtext-ex1.pdf")

## For now we are using the original device functions to draw axis labels
plot(1, type = "n")

## Then turn showtext on and draw some characters
showtext_begin()
text(1, 1.2, intToUtf8(c(21315, 31179, 19975, 36733)), cex = 5)

## Use another font
if("simkai.ttf" %in% font_files()) font_add("kaishu", "simkai.ttf")
text(1, 0.8, intToUtf8(c(19968, 32479, 27743, 28246)),
     cex = 5, family = "kaishu")
     
## Turn showtext off
showtext_end()

## Also turn off the device
dev.off()


###  Download font file from web  ###

download.file("http://fontpro.com/download-family.php?file=36289",
              "newrocker.ttf", mode="wb")
download.file("http://fontpro.com/download-family.php?file=35128",
              "cutetumblr.ttf", mode ="wb")

font_add("newrocker", "newrocker.ttf")
font_add("cutetumblr", "cutetumblr.ttf")

png("showtext-ex2.png", 800, 500)
plot(1, type = "n")
showtext_begin()
text(1, 1.2, "Let me tell you a story", cex = 4, family = "newrocker")
text(1, 0.8, "Long long ago...", cex = 4, family = "cutetumblr")
showtext_end()
dev.off()

setwd(old)


## End(Not run)