Package 'gdtools'

Title: Font Metrics and Font Management Utilities for R Graphics
Description: Compute text metrics (width, ascent, descent) using 'Cairo' and 'FreeType', independently of the active graphic device. Font lookup is delegated to 'systemfonts'. Additional utilities let users register 'Google Fonts' or bundled 'Liberation' fonts, check font availability, and assemble 'htmlDependency' objects so that fonts are correctly embedded in 'Shiny' applications, 'R Markdown' documents, and 'htmlwidgets' outputs such as 'ggiraph'.
Authors: David Gohel [aut, cre], Hadley Wickham [aut], Lionel Henry [aut], Jeroen Ooms [aut] (ORCID: <https://orcid.org/0000-0002-4035-0289>), Yixuan Qiu [ctb], R Core Team [cph] (Cairo code from X11 device), ArData [cph], RStudio [cph]
Maintainer: David Gohel <[email protected]>
License: GPL-3 | file LICENSE
Version: 0.5.1
Built: 2026-05-25 17:20:30 UTC
Source: https://github.com/davidgohel/gdtools

Help Index

Use a Font in Shiny or Markdown

Description

Add an empty HTML element attached to an 'HTML Dependency' containing the css and the font files so that the font is available in the HTML page. Multiple families are supported.

The htmlDependency is defined with function gfontHtmlDependency().

Usage

addGFontHtmlDependency(family = "Open Sans", subset = c("latin", "latin-ext"))

Arguments

family

family name of a 'Google Fonts', for example, "Open Sans", "Roboto", "Fira Code" or "Fira Sans Condensed". Complete list is available with the following command: 

gfonts::get_all_fonts()$family |>
  unlist() |>
  unique() |>
  sort()
subset

font subset, a character vector, it defaults to only "latin" and "latin-ext" and can contains values such as "greek", "emoji", "chinese-traditional",

Run the following code to get a complete list: 

gfonts::get_all_fonts()$subsets |> unlist() |> unique() |> sort()

Details

It allows users to use fonts from 'Google Fonts' in an HTML page generated by 'shiny' or 'R Markdown'. At the first request, the font files will be downloaded and stored in a cache on the user's machine, thus avoiding many useless downloads or allowing to work with these fonts afterwards without an Internet connection, in a docker image for example. See fonts_cache_dir().

The server delivering the font files should not be too busy. That's why a one second pause is added after each download to respect the server's limits. This time can be set with the option GFONTS_DOWNLOAD_SLEEPTIME which must be a number of seconds.

Value

an HTML object

See Also

Other functions for font management: fonts_cache_dir(), gfontHtmlDependency(), install_gfont_script(), installed_gfonts(), liberationmonoHtmlDependency(), liberationsansHtmlDependency(), liberationserifHtmlDependency(), register_gfont(), register_liberationmono(), register_liberationsans(), register_liberationserif()

Examples

## Not run: 
if (check_gfonts()) {
  dummy_setup()
  addGFontHtmlDependency(family = "Open Sans")
}

## End(Not run)

Check if font family exists.

Description

Check if a font family exists in available fonts.

Usage

font_family_exists(font_family = "sans", system_only = FALSE)

Arguments

font_family

font family name (case sensitive)
system_only

If TRUE, only look in system-installed fonts (as returned by systemfonts::system_fonts()). This is useful to verify that a font will be found by fontconfig, which is the font resolution mechanism used by Cairo devices at rendering time. When FALSE (the default), both system and registered fonts are considered.

Value

A logical value

Examples

font_family_exists("sans")
font_family_exists("Arial")
font_family_exists("Courier")
font_family_exists("Arial", system_only = TRUE)

Google Font specification

Description

Create a font specification for a Google Font, to be used with font_set().

Usage

font_google(family, subset = c("latin", "latin-ext"))

Arguments

family

family name of a 'Google Fonts', for example, "Open Sans", "Roboto", "Fira Code" or "Fira Sans Condensed".
subset

font subset, a character vector, it defaults to only "latin" and "latin-ext".

Value

An object of class font_spec.

See Also

Other font set functions: font_liberation(), font_set(), font_set_auto(), font_set_liberation()

Examples

font_google("Roboto")

Liberation Font specification

Description

Create a font specification for a Liberation font, to be used with font_set().

Usage

font_liberation(variant = c("sans", "serif", "mono"))

Arguments

variant

one of "sans", "serif", or "mono".

Value

An object of class font_spec.

See Also

Other font set functions: font_google(), font_set(), font_set_auto(), font_set_liberation()

Examples

font_liberation("sans")
font_liberation("mono")

Create a font set

Description

Bundle font registration, HTML dependencies, and font family names into a single object. Each argument accepts a font_google() specification, a font_liberation() specification, or a plain character string naming a system font already available.

The returned object provides fields ready to use with ggplot2::theme() (⁠$sans⁠, ⁠$serif⁠, ⁠$mono⁠), girafe(fonts = ...) or dsvg(fonts = ...) (⁠$dsvg_fonts⁠), and girafe(dependencies = ...) (⁠$dependencies⁠).

Usage

font_set(sans = NULL, serif = NULL, mono = NULL, symbol = NULL)

Arguments

sans

font for sans-serif text.
serif

font for serif text.
mono

font for monospace text.
symbol

font for symbol text.

Value

An object of class font_set with elements:

sans

character, the sans font family name (or NULL)

serif

character, the serif font family name (or NULL)

mono

character, the mono font family name (or NULL)

symbol

character, the symbol font family name (or NULL)

dependencies

list of htmlDependency objects

dsvg_fonts

named list of family names for dsvg()

sources

named list of source labels

See Also

font_set_liberation(), font_set_auto()

Other font set functions: font_google(), font_liberation(), font_set_auto(), font_set_liberation()

Examples

fonts <- font_set(sans = font_liberation("sans"))
fonts$sans
fonts$dsvg_fonts
fonts$dependencies

Automatic font set

Description

Build a font_set() by detecting the best available system fonts for each role (sans, serif, mono, symbol).

For each role a list of well-known fonts is tried in order. When none is found on the system, the corresponding Liberation font is used as a guaranteed offline fallback.

Role Candidates (in order) Fallback
sans Arial, Helvetica, DejaVu Sans Liberation Sans
serif Times New Roman, Times, DejaVu Serif Liberation Serif
mono Courier New, Courier, DejaVu Sans Mono Liberation Mono
symbol Symbol, Apple Symbols Liberation Sans

Usage

font_set_auto()

Value

An object of class font_set.

See Also

font_set(), font_set_liberation()

Other font set functions: font_google(), font_liberation(), font_set(), font_set_liberation()

Examples

fonts <- font_set_auto()
fonts

Liberation font set

Description

Shortcut to create a font_set() with all four font roles using Liberation fonts (Sans, Serif, Mono) and Liberation Sans as a fallback for symbols.

Usage

font_set_liberation()

Value

An object of class font_set.

See Also

font_set(), font_set_auto()

Other font set functions: font_google(), font_liberation(), font_set(), font_set_auto()

Examples

fonts <- font_set_liberation()
fonts

Manage Font Working Directory

Description

Initialize or remove font directory used to store downloaded font files.

This directory is managed by R function R_user_dir() but can also be defined in a non-user location by setting ENV variable GDTOOLS_CACHE_DIR or by setting R option GDTOOLS_CACHE_DIR.

Its value can be read with the fonts_cache_dir() function.

The directory can be deleted with rm_fonts_cache() and created with init_fonts_cache().

Usage

fonts_cache_dir()

rm_fonts_cache()

init_fonts_cache()

See Also

Other functions for font management: addGFontHtmlDependency(), gfontHtmlDependency(), install_gfont_script(), installed_gfonts(), liberationmonoHtmlDependency(), liberationsansHtmlDependency(), liberationserifHtmlDependency(), register_gfont(), register_liberationmono(), register_liberationsans(), register_liberationserif()

Examples

fonts_cache_dir()

options(GDTOOLS_CACHE_DIR = tempdir())
fonts_cache_dir()
options(GDTOOLS_CACHE_DIR = NULL)

Sys.setenv(GDTOOLS_CACHE_DIR = tempdir())
fonts_cache_dir()
Sys.setenv(GDTOOLS_CACHE_DIR = "")



init_fonts_cache()
dir.exists(fonts_cache_dir())

rm_fonts_cache()
dir.exists(fonts_cache_dir())

'Google Font' HTML dependency

Description

Create an HTML dependency ready to be used in 'Shiny' or 'R Markdown'.

Usage

gfontHtmlDependency(family = "Open Sans", subset = c("latin", "latin-ext"))

Arguments

family

family name of a 'Google Fonts', for example, "Open Sans", "Roboto", "Fira Code" or "Fira Sans Condensed". Complete list is available with the following command: 

gfonts::get_all_fonts()$family |>
  unlist() |>
  unique() |>
  sort()
subset

font subset, a character vector, it defaults to only "latin" and "latin-ext" and can contains values such as "greek", "emoji", "chinese-traditional",

Run the following code to get a complete list: 

gfonts::get_all_fonts()$subsets |> unlist() |> unique() |> sort()

Details

It allows users to use fonts from 'Google Fonts' in an HTML page generated by 'shiny' or 'R Markdown'. At the first request, the font files will be downloaded and stored in a cache on the user's machine, thus avoiding many useless downloads or allowing to work with these fonts afterwards without an Internet connection, in a docker image for example. See fonts_cache_dir().

The server delivering the font files should not be too busy. That's why a one second pause is added after each download to respect the server's limits. This time can be set with the option GFONTS_DOWNLOAD_SLEEPTIME which must be a number of seconds.

Value

an object defined with htmltools::htmlDependency().

See Also

Other functions for font management: addGFontHtmlDependency(), fonts_cache_dir(), install_gfont_script(), installed_gfonts(), liberationmonoHtmlDependency(), liberationsansHtmlDependency(), liberationserifHtmlDependency(), register_gfont(), register_liberationmono(), register_liberationsans(), register_liberationserif()

Examples

## Not run: 
if (check_gfonts()) {
  dummy_setup()
  gfontHtmlDependency(family = "Open Sans")
}

## End(Not run)

Shell command to install a font from 'Google Fonts'

Description

Create a string containing a system command to execute so that the font from 'Google Fonts' is installed on the system. Its execution may require root permissions, in dockerfile for example.

Usage

install_gfont_script(
  family = "Open Sans",
  subset = c("latin", "latin-ext"),
  platform = c("debian", "windows", "macos"),
  file = NULL
)

Arguments

family

family name of a 'Google Fonts', for example, "Open Sans", "Roboto", "Fira Code" or "Fira Sans Condensed". Complete list is available with the following command: 

gfonts::get_all_fonts()$family |>
  unlist() |>
  unique() |>
  sort()
subset

font subset, a character vector, it defaults to only "latin" and "latin-ext" and can contains values such as "greek", "emoji", "chinese-traditional",

Run the following code to get a complete list: 

gfonts::get_all_fonts()$subsets |> unlist() |> unique() |> sort()
platform

"debian" and "windows" and "macos" are supported.
file

script file to generate, optional. If the parameter is specified, a file will be generated ready for execution. If the platform is Windows, administration rights are required to run the script.

Details

It allows users to use fonts from 'Google Fonts' in an HTML page generated by 'shiny' or 'R Markdown'. At the first request, the font files will be downloaded and stored in a cache on the user's machine, thus avoiding many useless downloads or allowing to work with these fonts afterwards without an Internet connection, in a docker image for example. See fonts_cache_dir().

The server delivering the font files should not be too busy. That's why a one second pause is added after each download to respect the server's limits. This time can be set with the option GFONTS_DOWNLOAD_SLEEPTIME which must be a number of seconds.

Value

the 'shell' or 'PowerShell' command as a string

See Also

Other functions for font management: addGFontHtmlDependency(), fonts_cache_dir(), gfontHtmlDependency(), installed_gfonts(), liberationmonoHtmlDependency(), liberationsansHtmlDependency(), liberationserifHtmlDependency(), register_gfont(), register_liberationmono(), register_liberationsans(), register_liberationserif()

Examples

## Not run: 
if (check_gfonts()) {
  dummy_setup()
  install_gfont_script(family = "Roboto", platform = "macos")
}

## End(Not run)

List installed 'Google Fonts'

Description

List installed 'Google Fonts' that can be found in the user cache directory.

Usage

installed_gfonts()

Value

families names as a character vector

See Also

Other functions for font management: addGFontHtmlDependency(), fonts_cache_dir(), gfontHtmlDependency(), install_gfont_script(), liberationmonoHtmlDependency(), liberationsansHtmlDependency(), liberationserifHtmlDependency(), register_gfont(), register_liberationmono(), register_liberationsans(), register_liberationserif()

Examples

## Not run: 
if (check_gfonts()) {
  dummy_setup()
  register_gfont(family = "Roboto")
  installed_gfonts()
}

## End(Not run)

'Liberation Mono' Font HTML dependency

Description

Create an HTML dependency ready to be used in 'Shiny' or 'R Markdown' with 'Liberation Mono' Font.

Usage

liberationmonoHtmlDependency()

See Also

font_set_liberation(), font_set(), gfontHtmlDependency()

Other functions for font management: addGFontHtmlDependency(), fonts_cache_dir(), gfontHtmlDependency(), install_gfont_script(), installed_gfonts(), liberationsansHtmlDependency(), liberationserifHtmlDependency(), register_gfont(), register_liberationmono(), register_liberationsans(), register_liberationserif()

'Liberation Sans' Font HTML dependency

Description

Create an HTML dependency ready to be used in 'Shiny' or 'R Markdown' with 'Liberation Sans' Font.

Usage

liberationsansHtmlDependency()

See Also

font_set_liberation(), font_set(), gfontHtmlDependency()

Other functions for font management: addGFontHtmlDependency(), fonts_cache_dir(), gfontHtmlDependency(), install_gfont_script(), installed_gfonts(), liberationmonoHtmlDependency(), liberationserifHtmlDependency(), register_gfont(), register_liberationmono(), register_liberationsans(), register_liberationserif()

'Liberation Serif' Font HTML dependency

Description

Create an HTML dependency ready to be used in 'Shiny' or 'R Markdown' with 'Liberation Serif' Font.

Usage

liberationserifHtmlDependency()

See Also

font_set_liberation(), font_set(), gfontHtmlDependency()

Other functions for font management: addGFontHtmlDependency(), fonts_cache_dir(), gfontHtmlDependency(), install_gfont_script(), installed_gfonts(), liberationmonoHtmlDependency(), liberationsansHtmlDependency(), register_gfont(), register_liberationmono(), register_liberationsans(), register_liberationserif()

Register a 'Google Font'

Description

Register a font from 'Google Fonts' so that it can be used with devices using the 'systemfonts' package, i.e. the 'flextable' package and graphic outputs generated with the 'ragg', 'svglite' and 'ggiraph' packages.

Usage

register_gfont(family = "Open Sans", subset = c("latin", "latin-ext"))

Arguments

family

family name of a 'Google Fonts', for example, "Open Sans", "Roboto", "Fira Code" or "Fira Sans Condensed". Complete list is available with the following command: 

gfonts::get_all_fonts()$family |>
  unlist() |>
  unique() |>
  sort()
subset

font subset, a character vector, it defaults to only "latin" and "latin-ext" and can contains values such as "greek", "emoji", "chinese-traditional",

Run the following code to get a complete list: 

gfonts::get_all_fonts()$subsets |> unlist() |> unique() |> sort()

Details

It allows users to use fonts from 'Google Fonts' in an HTML page generated by 'shiny' or 'R Markdown'. At the first request, the font files will be downloaded and stored in a cache on the user's machine, thus avoiding many useless downloads or allowing to work with these fonts afterwards without an Internet connection, in a docker image for example. See fonts_cache_dir().

The server delivering the font files should not be too busy. That's why a one second pause is added after each download to respect the server's limits. This time can be set with the option GFONTS_DOWNLOAD_SLEEPTIME which must be a number of seconds.

Value

TRUE if the operation went ok.

See Also

Other functions for font management: addGFontHtmlDependency(), fonts_cache_dir(), gfontHtmlDependency(), install_gfont_script(), installed_gfonts(), liberationmonoHtmlDependency(), liberationsansHtmlDependency(), liberationserifHtmlDependency(), register_liberationmono(), register_liberationsans(), register_liberationserif()

Examples

## Not run: 
if (check_gfonts()) {
  dummy_setup()
  register_gfont(family = "Roboto")
}

## End(Not run)

Register font 'Liberation Mono'

Description

Register font 'Liberation Mono' so that it can be used with devices using the 'systemfonts' package, i.e. the 'flextable' package and graphic outputs generated with the 'ragg', 'svglite' and 'ggiraph' packages.

Usage

register_liberationmono(name = "Liberation Mono")

Arguments

name

the name to use for the font family when registering with 'systemfonts'. Using a custom name (e.g. "sans", "serif", "mono") allows devices like 'ragg' to resolve generic family names to this font.

Value

TRUE if the operation went ok.

See Also

font_set_liberation(), font_set()

Other functions for font management: addGFontHtmlDependency(), fonts_cache_dir(), gfontHtmlDependency(), install_gfont_script(), installed_gfonts(), liberationmonoHtmlDependency(), liberationsansHtmlDependency(), liberationserifHtmlDependency(), register_gfont(), register_liberationsans(), register_liberationserif()

Examples

register_liberationmono()
register_liberationmono(name = "mono")

Register font 'Liberation Sans'

Description

Register font 'Liberation Sans' so that it can be used with devices using the 'systemfonts' package, i.e. the 'flextable' package and graphic outputs generated with the 'ragg', 'svglite' and 'ggiraph' packages.

Usage

register_liberationsans(name = "Liberation Sans")

Arguments

name

the name to use for the font family when registering with 'systemfonts'. Using a custom name (e.g. "sans", "serif", "mono") allows devices like 'ragg' to resolve generic family names to this font.

Value

TRUE if the operation went ok.

See Also

font_set_liberation(), font_set()

Other functions for font management: addGFontHtmlDependency(), fonts_cache_dir(), gfontHtmlDependency(), install_gfont_script(), installed_gfonts(), liberationmonoHtmlDependency(), liberationsansHtmlDependency(), liberationserifHtmlDependency(), register_gfont(), register_liberationmono(), register_liberationserif()

Examples

register_liberationsans()
register_liberationsans(name = "sans")

Register font 'Liberation Serif'

Description

Register font 'Liberation Serif' so that it can be used with devices using the 'systemfonts' package, i.e. the 'flextable' package and graphic outputs generated with the 'ragg', 'svglite' and 'ggiraph' packages.

Usage

register_liberationserif(name = "Liberation Serif")

Arguments

name

the name to use for the font family when registering with 'systemfonts'. Using a custom name (e.g. "sans", "serif", "mono") allows devices like 'ragg' to resolve generic family names to this font.

Value

TRUE if the operation went ok.

See Also

font_set_liberation(), font_set()

Other functions for font management: addGFontHtmlDependency(), fonts_cache_dir(), gfontHtmlDependency(), install_gfont_script(), installed_gfonts(), liberationmonoHtmlDependency(), liberationsansHtmlDependency(), liberationserifHtmlDependency(), register_gfont(), register_liberationmono(), register_liberationsans()

Examples

register_liberationserif()
register_liberationserif(name = "serif")

Compute strings sizes

Description

Determines widths, ascent and descent in inches. Font lookup is performed by 'systemfonts' (so any font registered via systemfonts::register_font(), register_gfont(), or font_set() is found), then Cairo computes the actual metrics. The results are accurate for devices whose rendering finds the same font – this is guaranteed for 'systemfonts'-based devices (ragg, svglite, ggiraph) and true for Cairo devices (cairo_pdf(), ...) when the font is also installed at the system level. For devices with their own font engine (pdf(), png(), ...) the metrics may not match the rendering.

Usage

strings_sizes(
  x,
  fontname = "sans",
  fontsize = 10,
  bold = FALSE,
  italic = FALSE
)

Arguments

x

A character vector of strings to measure. All arguments are vectorized and recycled to match the length of x.
fontname

A character vector specifying the font family name (e.g., "sans", "serif", "mono"). Default is "sans". This argument is vectorized.
fontsize

A numeric vector specifying the font size in points. Default is 10. This argument is vectorized.
bold

A logical vector indicating whether the text should be bold. Default is FALSE. This argument is vectorized.
italic

A logical vector indicating whether the text should be italic. Default is FALSE. This argument is vectorized.

See Also

Other functions for font metrics: m_str_extents(), str_metrics()

Examples

strings_sizes(letters)
strings_sizes("Hello World!", bold = TRUE, italic = FALSE,
  fontname = "sans", fontsize = 12)

List fonts for 'systemfonts'.

Description

List system and registry fonts into a data.frame containing columns such as path, family, style, weight and italic.

Usage

sys_fonts()

Value

A data.frame of font information.

Examples

sys_fonts()

Version numbers of C libraries

Description

Return the runtime version of the Cairo and FreeType libraries linked to the package.

Usage

version_freetype()

version_cairo()

Value

An object of class "numeric_version".

Examples

version_cairo()
version_freetype()