R: Rendering Text for R Graphics Devices

showtext_begin {showtext} | R Documentation

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

[Package showtext version 0.7-1 Index]