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

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

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

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:

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

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

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/>