Package 'sysfonts'

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)

---

Load Google Fonts into 'sysfonts'

Description

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

This function will search the Google Fonts repository (https://fonts.google.com/) for a specified family name, download the proper font files, and then add them to sysfonts. This function requires the jsonlite and curl packages.

Usage

font_add_google(
  name,
  family = name,
  regular.wt = 400,
  bold.wt = 700,
  repo = "http://fonts.gstatic.com/",
  db_cache = TRUE,
  handle = curl::new_handle()
)

font.add.google(
  name,
  family = name,
  regular.wt = 400,
  bold.wt = 700,
  repo = "http://fonts.gstatic.com/",
  handle = curl::new_handle()
)

Arguments

name	name of the font that will be searched in Google Fonts
family	specifies the family name of this font in R. This can be any string, not necessarily the same as name. The value of this parameter will be used in R plotting functions. See the example code below.
regular.wt	font weight for the regular font face, usually 400
bold.wt	font weight for the bold font face, usually 700
repo	the site that hosts the font files. Default is the official repository http://fonts.gstatic.com/ provided by Google Fonts.
db_cache	whether to obtain font metadata from a cache site. Using cache is typically faster, but not as update-to-date as using the official API. If db_cache is set to FALSE, then metadata are retrieved from the Google Fonts API.
handle	a curl handle object passed to curl::curl_download().

Details

There are thousands of open source fonts in the Google Fonts repository (https://fonts.google.com/). This function will try to search the font family specified by the name argument, and then automatically download the font files for all possible font faces ("regular", "bold", "italic" and "bold italic", but no"symbol"). If fonts are found and downloaded successfully, they will be also added to sysfonts with the given family name.

Author(s)

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

See Also

font_families_google()

Examples

## Not run: 
font_add_google("Alegreya Sans", "aleg")

if(require(showtext))
{
    wd = setwd(tempdir())
    pdf("google-fonts-ex.pdf")
    showtext_begin()
    
    par(family = "aleg")
    plot(0:5,0:5, type="n")
    text(1:4, 1:4, "Alegreya Sans", font=1:4, cex = 2)
    
    showtext_end()
    dev.off()
    setwd(wd)
}


## End(Not run)

---

List Font Families Loaded by 'sysfonts'

Description

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

This function lists font families currently available that can be used by R2SWF and showtext packages.

Usage

font_families()

font.families()

Details

By default there are three font families loaded automatically, i.e., "sans", "serif" and "mono". If one wants to use other fonts, font_add() needs to be called to register new fonts by specifying a family name and corresponding font files. See font_add() for details about the meaning of "family name" in this context, as well as a complete example of registering and using a new font.

Value

A character vector of available font family names.

Author(s)

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

See Also

font_add()

Examples

font_families()

---

List Font Families Available in Google Fonts

Description

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

This function lists family names of the fonts that are currently available in Google Fonts. When running this function for the first time, it may take a few seconds to fetch the font information database. This function requires the jsonlite and curl packages.

Usage

font_families_google(db_cache = TRUE, handle = curl::new_handle())

font.families.google()

Arguments

db_cache	whether to obtain font metadata from a cache site. Using cache is typically faster, but not as update-to-date as using the official API. If db_cache is set to FALSE, then metadata are retrieved from the Google Fonts API.
handle	a curl handle object passed to curl::curl_download() and curl::curl_fetch_memory().

Value

A character vector of available font family names in Google Fonts.

Author(s)

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

See Also

font_add_google()

Examples

## Not run: 
font_families_google()

## End(Not run)

---

List Font Files Available in the Search Paths

Description

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

This function lists font files in the search path that can be loaded by font_add(). Currently supported formats include TrueType fonts(*.ttf, *.ttc) and OpenType fonts(*.otf).

Usage

font_files()

font.files()

Value

A data frame containing the following information of the font files:

path	The directory that the font file is located in.
file	File name of the font.
family	Family name.
face	Font face.
version	Version of the font.
ps_name	PostScript font name.

Author(s)

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

See Also

font_paths(), font_add()

Examples

## Not run: 
font_files()

## End(Not run)

---

Display Information of Available Google Fonts

Description

This function returns a data frame that contains the metadata of font families available in Google Fonts, for example the family name, available font face variants, the version number, etc. When running this function for the first time, it may take a few seconds to fetch the database. This function requires the jsonlite and curl packages.

Usage

font_info_google(db_cache = TRUE, handle = curl::new_handle())

Arguments

db_cache	whether to obtain font metadata from a cache site. Using cache is typically faster, but not as update-to-date as using the official API. If db_cache is set to FALSE, then metadata are retrieved from the Google Fonts API.
handle	a curl handle object passed to curl::curl_download() and curl::curl_fetch_memory().

Value

A data frame containing metadata of Google Fonts.

Author(s)

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

See Also

font_families_google()

Examples

## Not run: 
font_info_google()

## End(Not run)

---

Get/Set Font Search Paths

Description

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

This function gets/sets the search paths for font files. See font_add() for details about how sysfonts looks for font files. There is also a complete example showing the usage of these functions in the help page of font_add().

Usage

font_paths(new)

font.paths(new)

Arguments

new	a character vector indicating the search paths to be prepended. If the argument is missing, the function will return the current search paths.

Details

Default search paths will be assigned when package is loaded:

• For Windows, it is %windir%\Fonts, usually expanded into C:\Windows\Fonts

• For Mac OS, default paths are /Library/Fonts and ~/Library/Fonts and their subdirectories

• For Linux and other Unix-like OS, /usr/share/fonts, /usr/local/share/fonts, ~/.fonts, ~/.local/share/fonts, and their subdirectories

Value

The updated search paths.

Author(s)

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

---