Help for package gdtools

Title:

Font Metrics and Font Management Utilities for R Graphics

Version:

0.5.0

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'.

License:

GPL-3 | file LICENSE

URL:

https://davidgohel.github.io/gdtools/

BugReports:

https://github.com/davidgohel/gdtools/issues

Depends:

R (≥ 4.0.0)

Imports:

fontquiver (≥ 0.2.0), htmltools, Rcpp (≥ 0.12.12), systemfonts (≥ 1.3.1), tools

Suggests:

curl, gfonts, methods, testthat

LinkingTo:

Rcpp

Encoding:

UTF-8

RoxygenNote:

7.3.3

SystemRequirements:

cairo, freetype2, fontconfig

NeedsCompilation:

yes

Packaged:

2026-02-08 23:07:28 UTC; davidgohel

Author:

David Gohel [aut, cre], Hadley Wickham [aut], Lionel Henry [aut], Jeroen Ooms

[aut], Yixuan Qiu [ctb], R Core Team [cph] (Cairo code from X11 device), ArData [cph], RStudio [cph]

Maintainer:

David Gohel <david.gohel@ardata.fr>

Repository:

CRAN

Date/Publication:

2026-02-09 06:10:44 UTC

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

Examples

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

## End(Not run)

Checks the operability of 'gfonts'

Description

Checks that 'gfonts' is installed and can be used. Packages 'curl' and 'gfonts' must be installed and internet connectivity must be active.

Usage

check_gfonts(errors = FALSE)

Arguments

errors

if TRUE, function is triggering errors if a condition is not satisfied.

Value

TRUE or FALSE

Set up a temporary font cache

Description

Create a temporary directory used as the 'Google Fonts' cache. This is intended for examples and tests.

Usage

dummy_setup()

Value

The path to the temporary cache directory (invisibly).

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.

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.

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

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.

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.

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

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

Value

an object defined with htmltools::htmlDependency().

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

Value

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

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

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

'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()

'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()

Compute string extents for a vector of strings.

Description

For each x element, determines the width and height of a bounding box that's big enough to (just) enclose the provided text. Unit is points.

Usage

m_str_extents(
  x,
  fontname = "sans",
  fontsize = 10,
  bold = FALSE,
  italic = FALSE,
  fontfile = NULL
)

Arguments

x

Character vector of strings to measure

fontname

Font name. A character vector, recycled to match x.

fontsize

Font size. A numeric vector, recycled to match x.

bold, italic

Is text bold/italic? A logical vector, recycled to match x.

fontfile

Font file. A character vector, recycled to match x.

Note

This function will be deprecated in a future release. Use strings_sizes() instead.

Examples


# The first run can be slow when font caches are missing
# as font files are then being scanned to build those font caches.
m_str_extents(letters, fontsize = 1:26)
m_str_extents(letters[1:3],
  bold = c(TRUE, FALSE, TRUE),
  italic = c(FALSE, TRUE, TRUE),
  fontname = c("sans", "sans", "sans") )

Find best family match with systemfonts

Description

match_family() returns the best font family match.

Usage

match_family(font = "sans", bold = TRUE, italic = TRUE, debug = NULL)

Arguments

font

family or face to match.

bold

Whether to match a font featuring a bold face.

italic

Whether to match a font featuring an italic face.

debug

deprecated

Examples

match_family("sans")
match_family("serif")

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

Value

TRUE if the operation went ok.

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.

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

Value

TRUE if the operation went ok.

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

Value

TRUE if the operation went ok.

Examples

register_liberationserif()
register_liberationserif(name = "serif")

Set and unset a minimalistic Fontconfig configuration

Description

Set and unset a minimalistic Fontconfig configuration

Usage

set_dummy_conf()

Note

Fontconfig is not used anymore and these functions will be deprecated in the next release.

Get font metrics for a string.

Description

Compute the width, ascent and descent of a single string in points using Cairo text measurement.

Usage

str_metrics(
  x,
  fontname = "sans",
  fontsize = 12,
  bold = FALSE,
  italic = FALSE,
  fontfile = ""
)

Arguments

x

Character vector of strings to measure (only the first element is used).

fontname

Font name.

fontsize

Font size in points.

bold, italic

Is text bold/italic?

fontfile

Path to a font file. If empty, the font is resolved by name via systemfonts.

Value

A named numeric vector with elements width, ascent and descent (unit is points).

Note

This function will be deprecated in a future release. Use strings_sizes() instead.

Examples

str_metrics("Hello World!")

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.

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

Use a Font in Shiny or Markdown

Description

Usage

Arguments

Details

Value

See Also

Examples

Checks the operability of 'gfonts'

Description

Usage

Arguments

Value

Set up a temporary font cache

Description

Usage

Value

Check if font family exists.

Description

Usage

Arguments

Value

Examples

Google Font specification

Description

Usage

Arguments

Value

See Also

Examples

Liberation Font specification

Description

Usage

Arguments

Value

See Also

Examples

Create a font set

Description

Usage

Arguments

Value

See Also

Examples

Automatic font set

Description

Usage

Value

See Also

Examples

Liberation font set

Description

Usage

Value

See Also

Examples

Manage Font Working Directory

Description

Usage

See Also

Examples

'Google Font' HTML dependency

Description

Usage

Arguments

Details

Value

See Also

Examples

Shell command to install a font from 'Google Fonts'

Description

Usage

Arguments

Details

Value

See Also

Examples

List installed 'Google Fonts'

Description

Usage