R: Add New Font Families to 'sysfonts'

font_add {sysfonts} | R Documentation

## Add New Font Families to 'sysfonts'

### Description

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

This function registers new font families that can be used by package showtext and the SWF device in package R2SWF. Currently supported formats include but not limited to TrueType fonts(*.ttf, *.ttc) and OpenType fonts(*.otf).

### Usage

    font_add(family, regular, bold = NULL, italic = NULL,
      bolditalic = NULL, symbol = NULL)

    font.add(family, regular, bold = NULL, italic = NULL,
      bolditalic = NULL, symbol = NULL)

### Arguments

`family` | a character string of maximum 200-byte size, indicating the family name of the font. See "Details" for further explanation.
`regular` | path of the font file for "regular" font face. This argument must be specified as a character string and cannot be missing.
`bold` | path of the font file for "bold" font face. If it is `NULL`, the function will use the value of argument `regular`.
`italic, bolditalic, symbol` | ditto

### Details

In R graphics device, there are two parameters combined together to select a font to show text. `par("family")` is a character string giving a name to a series of font faces. Here series implies that there may be different fonts with the same family name, and actually they are distinguished by the parameter `par("font")`, indicating whether it is regular, bold, or italic, etc. In R, `par("font")` is an integer from 1 to 5 representing regular, bold, italic, bold italic, and symbol, respectively.

In sysfonts package, there are three default font families, sans, serif, and mono, each with five font faces as mentioned above. If one wants to use other font families, the function `font_add()` needs to be called to register new fonts. Note that the `family` argument in this function can be an arbitrary string that does not need to be the real font name. The specified family name will be used in functions like `par(family = "myfont")` and `text("Some text", family = "myfont")`. The Examples section shows a complete demonstration of the usage.

To find the font file of argument `regular` (and the same for other font faces), this function will first check the existence of the specified path. If not found, file will be searched in the directories returned by `font_paths()` in turn. If the file cannot be found in any of the locations, an error will be issued.

### Value

A character vector (invisible) of currently available font family names.

### Author(s)

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

### See Also

See `par()` for explanation of the parameters `family` and `font`.

### Examples

    ## Not run:
    ## Example: download the font file of WenQuanYi Micro Hei,
    ##          add it to SWF device, and use it to draw text in swf().
    ##          WenQuanYi Micro Hei is an open source and high quality
    ##          Chinese (and CJKV) font.

    wd = setwd(tempdir())
    ft.url = "http://sourceforge.net/projects/wqy/files/wqy-microhei"
    ft.url = paste(ft.url, "0.2.0-beta/wqy-microhei-0.2.0-beta.tar.gz",
                   sep = "/")
    download.file(ft.url, basename(ft.url))

    ## Extract and add the directory to search path
    untar(basename(ft.url), compressed = "gzip")
    font_paths("wqy-microhei")

    ## Register this font file and assign the family name "wqy"
    ## Other font faces will be the same with regular by default
    font_add("wqy", regular = "wqy-microhei.ttc")

    ## A more concise way to add font is to give the path directly,
    ## without calling font_paths()
    # font_add("wqy", "wqy-microhei/wqy-microhei.ttc")

    ## List available font families
    font_families()

    if(require(R2SWF))
    {
        ## Now it shows that we can use the family "wqy" in swf()
        swf("testfont.swf")

        ## Select font family globally
        op = par(family = "serif", font.lab = 2)
        ## Inline selecting font
        plot(1, type = "n")
        text(1, 1, intToUtf8(c(20013, 25991)), family = "wqy", font = 1, cex = 2)

        dev.off()
        swf2html("testfont.swf")
    }

    setwd(wd)

    ## End(Not run)

[Package sysfonts version 0.8 Index]