systemfonts

https://rdrr.io/cran/systemfonts/
Admin
systemfonts is an R package that provides system native access to the font catalogue for locating...
Tokens:34,578
Snippets:236
Trust Score:9.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Load and Get Help for Systemfonts Package

Source: https://rdrr.io/cran/systemfonts/src/tools/winlibs.R

Loads the systemfonts R package and displays its help documentation. This is typically done after installing the package and its dependencies.

```r
library(systemfonts)
help(systemfonts)
```

--------------------------------

### Example Usage of get_fallback

Source: https://rdrr.io/cran/systemfonts/src/R/zzz.R

Demonstrates how to access the documentation for the get_fallback function in the systemfonts package.

```R
library(systemfonts) help(get_fallback)
```

--------------------------------

### Example Usage of clear_local_fonts

Source: https://rdrr.io/cran/systemfonts/src/R/register_font.R

Demonstrates how to use the `clear_local_fonts` function and access its help documentation.

```R
library(systemfonts) help(clear_local_fonts)
```

--------------------------------

### Calculate String Width in R

Source: https://rdrr.io/cran/systemfonts/man/string_width.html

Demonstrates basic usage of the string_width function with a character vector of strings. This example shows how to get pixel widths for different string lengths.

```r
strings <- c('A short string', 'A very very looong string')
string_width(strings)


```

--------------------------------

### Example Usage of as_font_width (R)

Source: https://rdrr.io/cran/systemfonts/src/R/match_fonts.R

Demonstrates the usage of the as_font_width function with a vector of common font width strings.

```R
as_font_width(
  c("undefined", "ultracondensed", "extracondensed", "condensed", "semicondensed",
  "normal", "semiexpanded", "expanded", "extraexpanded", "ultraexpanded")
)
```

--------------------------------

### Load systemfonts Package

Source: https://rdrr.io/cran/systemfonts/src/inst/doc/c_interface.R

Loads the systemfonts package into the R session. Ensure the package is installed before loading.

```r
library(systemfonts)
```

--------------------------------

### Example: Resetting Font Cache - R

Source: https://rdrr.io/cran/systemfonts/man/reset_font_cache.html

Demonstrates the effect of resetting the font cache. First, it captures the current list of fonts. After installing a new font (simulated by re-fetching the list), the cache is reset, and the font list is fetched again to show the updated results.

```r
all_fonts <- system_fonts()

##-- Install a new font on the system --##

all_fonts_new <- system_fonts()

## all_fonts_new will be equal to all_fonts

reset_font_cache()

all_fonts_new <- system_fonts()

## all_fonts_new will now contain the new font
```

--------------------------------

### List All System Fonts

Source: https://rdrr.io/cran/systemfonts/man/system_fonts.html

Call this function to get a data frame containing information about all fonts installed on your system. The data frame includes details for each font.

```R
system_fonts()
```

--------------------------------

### system_fonts()

Source: https://rdrr.io/cran/systemfonts/man/system_fonts.html

Lists all fonts installed on your system, returning a data frame with font information.

```APIDOC
## system_fonts()

### Description
List all fonts installed on your system 

### Usage
```
system_fonts()

```

### Value
A data frame with a row for each font and various information in each column 
### Examples
```R
# See all monospace fonts
fonts <- system_fonts()
fonts[fonts$monospace, ]


```
```

--------------------------------

### Download and Install Harfbuzz for Windows

Source: https://rdrr.io/cran/systemfonts/src/tools/winlibs.R

This script downloads and installs the harfbuzz library if it's not already present. It selects the correct download URL based on the R version and platform (e.g., clang, ucrt, aarch64). The downloaded archive is extracted, and the files are renamed to 'freetype2' in the '../windows' directory.

```r
if (!file.exists("../windows/harfbuzz/include/harfbuzz/hb.h")) {
  unlink("../windows", recursive = TRUE)
  url <- if (grepl("aarch", R.version$platform)) {
    "https://github.com/r-windows/bundles/releases/download/harfbuzz-8.2.1/harfbuzz-8.2.1-clang-aarch64.tar.xz"
  } else if (grepl("clang", Sys.getenv('R_COMPILED_BY'))) {
    "https://github.com/r-windows/bundles/releases/download/harfbuzz-8.2.1/harfbuzz-8.2.1-clang-x86_64.tar.xz"
  } else if (getRversion() >= "4.2") {
    "https://github.com/r-windows/bundles/releases/download/harfbuzz-8.2.1/harfbuzz-8.2.1-ucrt-x86_64.tar.xz"
  } else {
    "https://github.com/rwinlib/harfbuzz/archive/v2.7.4.tar.gz"
  }
  download.file(url, basename(url), quiet = TRUE)
  dir.create("../windows", showWarnings = FALSE)
  untar(basename(url), exdir = "../windows", tar = 'internal')
  unlink(basename(url))
  setwd("../windows")
  file.rename(list.files(), 'freetype2')
}
```

--------------------------------

### Example Usage of font_fallback

Source: https://rdrr.io/cran/systemfonts/src/R/font_fallback.R

Demonstrates how to call the font_fallback function with an emoji string to find a suitable fallback font.

```R
font_fallback("\U0001f604") # Smile emoji
```

--------------------------------

### Example Usage of search_web_fonts

Source: https://rdrr.io/cran/systemfonts/man/search_web_fonts.html

Demonstrates how to use the search_web_fonts function to find a font by its family name. Requires an internet connection to function.

```r
# Requires an internet connection

# search_web_fonts("Spectral")

```

--------------------------------

### Example Usage of font_feature

Source: https://rdrr.io/cran/systemfonts/src/R/font_feature.R

Demonstrates setting ligatures, letters, and numbers using descriptive names. It also shows how to use the 4-letter tag directly to access additional stylistic variants.

```R
font_feature(letters = "stylistic", numbers = c("lining", "tabular"))

# Use the tag directly to access additional stylistic variants
font_feature(numbers = c("lining", "tabular"), salt = 2)
```

--------------------------------

### Get System Fonts (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Retrieves a list of all available system fonts. Returns a data frame with font information.

```R
system_fonts_c <- function() {
  .Call(`_systemfonts_system_fonts_c`)
}
```

--------------------------------

### Get String Metrics (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Retrieves detailed metrics for strings based on font properties. Useful for precise text layout calculations.

```R
dev_string_metrics_c <- function(string, family, face, size, cex, unit) {
  .Call(`_systemfonts_dev_string_metrics_c`, string, family, face, size, cex, unit)
}
```

--------------------------------

### shape_string Function Documentation

Source: https://rdrr.io/cran/systemfonts/man/shape_string.html

This snippet details the shape_string function, its arguments, return value, and provides usage examples.

```APIDOC
## shape_string

### Description
Do basic text shaping of strings. This function will use freetype to calculate advances, doing kerning if possible. It will not perform any font substitution or ligature resolving and will thus be much in line with how the standard graphic devices does text shaping. Inputs are recycled to the length of `strings`.

### Usage
```R
shape_string(
  strings,
  id = NULL,
  family = "",
  italic = FALSE,
  bold = FALSE,
  size = 12,
  res = 72,
  lineheight = 1,
  align = "left",
  hjust = 0,
  vjust = 0,
  width = NA,
  tracking = 0,
  indent = 0,
  hanging = 0,
  space_before = 0,
  space_after = 0,
  path = NULL,
  index = 0
)
```

### Arguments

* `strings` (character vector): A character vector of strings to shape.
* `id` (vector, optional): A vector grouping the strings together. If strings share an id the shaping will continue between strings.
* `family` (character): The name of the font families to match.
* `italic` (logical): Logical indicating the font slant.
* `bold` (logical): Logical indicating whether the font weight.
* `size` (numeric): The pointsize of the font to use for size related measures.
* `res` (numeric): The ppi of the size related measures.
* `lineheight` (numeric): A multiplier for the lineheight.
* `align` (character): Within text box alignment, either 'left', 'center', or 'right'.
* `hjust`, `vjust` (numeric): The justification of the textbox surrounding the text.
* `width` (numeric, optional): The requested width of the string in inches. Setting this to something other than `NA` will turn on word wrapping.
* `tracking` (numeric): Tracking of the glyphs (space adjustment) measured in 1/1000 em.
* `indent` (numeric): The indent of the first line in a paragraph measured in inches.
* `hanging` (numeric): The indent of the remaining lines in a paragraph measured in inches.
* `space_before`, `space_after` (numeric): The spacing above and below a paragraph, measured in points.
* `path`, `index` (vector, optional): Path an index of a font file to circumvent lookup based on family and style.

### Value
A list with two elements: `shape` contains the position of each glyph, relative to the origin in the enclosing textbox. `metrics` contain metrics about the full strings.

`shape` is a data.frame with the following columns:

* `glyph` (character): The glyph as a character.
* `index` (integer): The index of the glyph in the font file.
* `metric_id` (integer): The index of the string the glyph is part of (referencing a row in the `metrics` data.frame).
* `string_id` (integer): The index of the string the glyph came from (referencing an element in the `strings` input).
* `x_offset` (numeric): The x offset in pixels from the origin of the textbox.
* `y_offset` (numeric): The y offset in pixels from the origin of the textbox.
* `x_mid` (numeric): The x offset in pixels to the middle of the glyph, measured from the origin of the glyph.

`metrics` is a data.frame with the following columns:

* `string` (character): The text the string consists of.
* `width` (numeric): The width of the string.
* `height` (numeric): The height of the string.
* `left_bearing` (numeric): The distance from the left edge of the textbox and the leftmost glyph.
* `right_bearing` (numeric): The distance from the right edge of the textbox and the rightmost glyph.
* `top_bearing` (numeric): The distance from the top edge of the textbox and the topmost glyph.
* `bottom_bearing` (numeric): The distance from the bottom edge of the textbox and the bottommost glyph.
* `left_border` (numeric): The position of the leftmost edge of the textbox related to the origin.
* `top_border` (numeric): The position of the topmost edge of the textbox related to the origin.
* `pen_x` (numeric): The horizontal position of the next glyph after the string.
* `pen_y` (numeric): The vertical position of the next glyph after the string.

### Examples

```R
string <- "This is a long string\nLook; It spans multiple lines\nand all"

# Shape with default settings
shape_string(string)

# Mix styles within the same string
string <- c(
  "This string will have\na ",
  "very large",
  " text style\nin the middle"
)

shape_string(string, id = c(1, 1, 1), size = c(12, 24, 12))
```
```

--------------------------------

### Get String Metrics with systemfonts

Source: https://rdrr.io/cran/systemfonts/src/R/dev_strings.R

Retrieves string metrics including width, ascent, and descent, as measured by the current graphics device. This allows for the construction of tight bounding boxes around strings. It is similar to `string_widths_dev` but provides more comprehensive dimensional information.

```R
string_metrics_dev <- function(
  strings,
  family = '',
  face = 1,
  size = 12,
  cex = 1,
  unit = 'cm'
) {
  unit <- match.arg(unit, possible_units)
  unit <- match(unit, possible_units) - 1L
  n_total <- length(strings)
  if (length(family) != 1) family <- rep_len(family, n_total)
  if (any(c(length(face), length(size), length(cex)) != 1)) {
    face <- rep_len(face, n_total)
    size <- rep_len(size, n_total)
    cex <- rep_len(cex, n_total)
  }
  dev_string_metrics_c(
    as.character(strings),
    as.character(family),
    as.integer(face),
    as.numeric(size),
    as.numeric(cex),
    unit
  )
}
```

--------------------------------

### Require a font family

Source: https://rdrr.io/cran/systemfonts/man/require_font.html

Use `require_font` to ensure a font family is available. This example checks for the 'sans' font, which should always be present on most systems.

```R
require_font("sans")
```

--------------------------------

### Register a font variant with OpenType features

Source: https://rdrr.io/cran/systemfonts/man/register_variant.html

This example demonstrates how to register a variant of an existing font family, applying specific OpenType features like ligatures. It includes steps to retrieve the font path, register the variant, view the updated registry, and clean up.

```r
sans <- match_fonts("sans")$path
sans <- system_fonts()$family[system_fonts()$path == sans][1]

# Register a variant of it:
register_variant(
  "sans_ligature",
  sans,
  features = font_feature(ligatures = "discretionary")
)

registry_fonts()

# clean up
clear_registry()
```

--------------------------------

### Get Registry Fonts (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Retrieves a list of fonts currently registered in the system. Returns a data frame.

```R
registry_fonts_c <- function() {
  .Call(`_systemfonts_registry_fonts_c`)
}
```

--------------------------------

### Get Font Info (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Retrieves detailed information about a specific font at a given index and size. Requires path, index, size, and resolution.

```R
get_font_info_c <- function(path, index, size, res) {
  .Call(`_systemfonts_get_font_info_c`, path, index, size, res)
}
```

--------------------------------

### Get Line Width (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Calculates the width of a line of text, with an option to include bearing. Requires string, path, index, size, resolution, and include_bearing flag.

```R
get_line_width_c <- function(string, path, index, size, res, include_bearing) {
  .Call(`_systemfonts_get_line_width_c`, string, path, index, size, res, include_bearing)
}
```

--------------------------------

### string_metrics_dev

Source: https://rdrr.io/cran/systemfonts/src/R/dev_strings.R

Get string metrics (width, ascent, descent) as measured by the current device. This function is useful for constructing tight bounding boxes around strings.

```APIDOC
## string_metrics_dev

### Description
Get string metrics as measured by the current device. This function is much like [string_widths_dev()] but also returns the ascent and descent of the string making it possible to construct a tight bounding box around the string.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **strings** (character vector) - A character vector of strings to measure
* **family** (character) - The font families to use. Will get recycled
* **face** (numeric/integer) - The font faces to use. Will get recycled
* **size** (numeric) - The font size to use. Will get recycled
* **cex** (numeric) - The cex multiplier to use. Will get recycled
* **unit** (character) - The unit to return the width in. Either "cm", "inches", "device", or "relative"

### Return Value
A data.frame with `width`, `ascent`, and `descent` columns giving the metrics in the requested unit.

### Examples
```R
# Get the metrics as measured in cm (default)
string_metrics_dev(c('some text', 'a string with descenders'))
```
```

--------------------------------

### Get Google Fonts Registry (WOFF2)

Source: https://rdrr.io/cran/systemfonts/src/R/web_fonts.R

Retrieves the Google Fonts registry for WOFF2 fonts. The registry is cached for subsequent calls.

```R
get_google_fonts_registry(woff2 = TRUE)
```

--------------------------------

### Get Glyph Info (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Retrieves information about specific glyphs within a font. Requires glyph identifiers, path, index, size, and resolution.

```R
get_glyph_info_c <- function(glyphs, path, index, size, res) {
  .Call(`_systemfonts_get_glyph_info_c`, glyphs, path, index, size, res)
}
```

--------------------------------

### Get String Widths with systemfonts

Source: https://rdrr.io/cran/systemfonts/src/R/dev_strings.R

Measures the width of strings as interpreted by the current graphics device. Useful for precise composition tasks where device-specific rendering is important. It offers direct, vectorised access for high performance.

```R
string_widths_dev <- function(
  strings,
  family = '',
  face = 1,
  size = 12,
  cex = 1,
  unit = 'cm'
) {
  unit <- match.arg(unit, possible_units)
  unit <- match(unit, possible_units) - 1L
  n_total <- length(strings)
  if (length(family) != 1) family <- rep_len(family, n_total)
  if (any(c(length(face), length(size), length(cex)) != 1)) {
    face <- rep_len(face, n_total)
    size <- rep_len(size, n_total)
    cex <- rep_len(cex, n_total)
  }
  dev_string_widths_c(
    as.character(strings),
    as.character(family),
    as.integer(face),
    as.numeric(size),
    as.numeric(cex),
    unit
  )
}
```

--------------------------------

### Get Font Fallback (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Retrieves font fallback information for a given path, index, and string. Used for character mapping.

```R
get_fallback_c <- function(path, index, string) {
  .Call(`_systemfonts_get_fallback_c`, path, index, string)
}
```

--------------------------------

### Get Glyph Outlines

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Retrieves the vector outlines for a given glyph. Requires glyph, path, index, size, tolerance, and verbosity.

```R
get_glyph_outlines <- function(glyph, path, index, size, tolerance, verbose) {
  .Call(`_systemfonts_get_glyph_outlines`, glyph, path, index, size, tolerance, verbose)
}
```

--------------------------------

### Get string metrics using string_metrics_dev

Source: https://rdrr.io/cran/systemfonts/man/string_metrics_dev.html

This function calculates string metrics like width, ascent, and descent. It accepts a character vector of strings and optional font parameters. The default unit is 'cm'.

```r
string_metrics_dev(
  strings,
  family = "",
  face = 1,
  size = 12,
  cex = 1,
  unit = "cm"
)


```

```r
# Get the metrics as measured in cm (default)
string_metrics_dev(c('some text', 'a string with descenders'))


```

--------------------------------

### Get Letter Tag

Source: https://rdrr.io/cran/systemfonts/src/R/font_feature.R

Converts a letter setting name (e.g., 'swash', 'stylistic') to its corresponding OpenType tag (e.g., 'cswh', 'salt'). Stops with an error if the name is not recognized.

```R
get_letter_tag <- function(x) {
  name <- c(
    "swash",
    "alternates",
    "historical",
    "localized",
    "randomize",
    "alt_annotation",
    "stylistic",
    "subscript",
    "superscript",
    "titling",
    "small_caps"
  )
  tags <- c(
    "cswh",
    "calt",
    "hist",
    "locl",
    "rand",
    "nalt",
    "salt",
    "subs",
    "sups",
    "titl",
    "smcp"
  )
  ind <- match(tolower(x), name)
  if (is.na(ind)) {
    stop(
      "No letter setting called '",
      x,
      "'. Use one of ",
      paste(name, collapse = ", "),
      call. = FALSE
    )
  }
  tags[ind]
}
```

--------------------------------

### R: Get Glyph Information

Source: https://rdrr.io/cran/systemfonts/src/R/font_info.R

This R code snippet demonstrates how to retrieve glyph information using the `get_glyph_info_c` function. It handles the logic for matching fonts if a path is not provided, and ensures that path, index, size, and resolution parameters are correctly formatted and repeated as necessary before calling the underlying C function. It also includes a check to ensure all provided paths are valid files.

```R
if (is.null(path)) {
    fonts <- match_fonts(
      rep_len(family, n_strings),
      rep_len(italic, n_strings),
      ifelse(rep_len(bold, n_strings), "bold", "normal")
    )
    path <- rep(fonts$path, n_glyphs)
    index <- rep(fonts$index, n_glyphs)
  } else {
    if (!all(c(length(path), length(index)) == 1)) {
      path <- rep(rep_len(path, n_strings), n_glyphs)
      index <- rep(rep_len(index, n_strings), n_glyphs)
    }
  }
  if (length(size) != 1) size <- rep(rep_len(size, n_strings), n_glyphs)
  if (length(res) != 1) res <- rep(rep_len(res, n_strings), n_glyphs)
  if (!all(file.exists(path)))
    stop("path must point to a valid file", call. = FALSE)
  get_glyph_info_c(
    glyphs,
    path,
    as.integer(index),
    as.numeric(size),
    as.numeric(res)
  )
}
```

--------------------------------

### add_fonts

Source: https://rdrr.io/cran/systemfonts/src/R/register_font.R

Adds local font files to the system's font search path. This function is useful for projects that need to be reproducible across systems or when administrator privileges are not available, allowing fonts to be loaded without a full system installation.

```APIDOC
## add_fonts

### Description
Adds local font files to the system's font search path. This function is useful for projects that need to be reproducible across systems or when administrator privileges are not available, allowing fonts to be loaded without a full system installation.

### Parameters
- **files** (character vector) - A character vector of font file paths or URLs to add.

### Return Value
This function is called for its side effects.

### Examples
```R
# example code
empty_font <- system.file("unfont.ttf", package = "systemfonts")

add_fonts(empty_font)

clear_local_fonts()
```
```

--------------------------------

### Load systemfonts package and view help

Source: https://rdrr.io/cran/systemfonts/src/tests/testthat/test-system_fonts.R

Loads the systemfonts R package and displays its help documentation. This is a common step for understanding package functionality.

```R
library(systemfonts) help(systemfonts)
```

--------------------------------

### Access Systemfonts Documentation

Source: https://rdrr.io/cran/systemfonts/src/tests/testthat.R

Load the systemfonts library and access its documentation using the help() function.

```r
library(systemfonts)
help(systemfonts)

```

--------------------------------

### List System Fonts in R

Source: https://rdrr.io/cran/systemfonts/src/R/system_fonts.R

Call this function to retrieve a data frame containing information about all fonts installed on your system. It's useful for inspecting available fonts and filtering them, for example, to find all monospace fonts.

```R
system_fonts <- function() {
  system_fonts_c()
}
```

```R
# See all monospace fonts
fonts <- system_fonts()
fonts[fonts$monospace, ]
```

--------------------------------

### Run Systemfonts Package Tests

Source: https://rdrr.io/cran/systemfonts/src/tests/testthat.R

Load the systemfonts and testthat libraries, then run the package tests.

```r
library(testthat)
library(systemfonts)

test_check("systemfonts")

```

--------------------------------

### R: Accessing help for glyph_info

Source: https://rdrr.io/cran/systemfonts/src/R/font_info.R

This R command shows how to access the help documentation for the `glyph_info` function in the `systemfonts` package.

```R
library(systemfonts) help(glyph_info)
```

--------------------------------

### Get Font Squirrel Registry

Source: https://rdrr.io/cran/systemfonts/src/R/web_fonts.R

Retrieves the Font Squirrel registry. The registry is cached for subsequent calls.

```R
font_squirrel_registry <- new.env(parent = emptyenv())
get_font_squirrel_registry <- function() {
  if (is.null(font_squirrel_registry$fonts)) {
    fonts <- jsonlite::read_json(
      "https://www.fontsquirrel.com/api/fontlist/all"
    )
    font_squirrel_registry$fonts <- do.call(
      rbind,
      lapply(fonts, function(x) {
        x <- data.frame(
          family = x$family_name,
          n_variants = x$family_count,
          url = paste0(
            "https://www.fontsquirrel.com/fonts/download/",
            x$family_urlname
          ),
          category = I(list(x$classification))
        )
        attr(x, "row.names") <- .set_row_names(nrow(x))
        x
      })
    )
  }
  font_squirrel_registry$fonts
}
```

--------------------------------

### reset_font_cache()

Source: https://rdrr.io/cran/systemfonts/src/R/system_fonts.R

Resets the system font cache. This is useful when new fonts are installed and need to be recognized by the systemfonts package.

```APIDOC
## Function: reset_font_cache

### Description
Resets the system font cache. Building the list of system fonts is time consuming and is therefore cached. This, in turn, means that changes to the system fonts (i.e. installing new fonts), will not propagate to systemfonts. The solution is to reset the cache, which will result in the next call to e.g. [match_fonts()] will trigger a rebuild of the cache.

### Example
```R
all_fonts <- system_fonts()

##-- Install a new font on the system --##

all_fonts_new <- system_fonts()

## all_fonts_new will be equal to all_fonts

reset_font_cache()

all_fonts_new <- system_fonts()

## all_fonts_new will now contain the new font
```
```

--------------------------------

### Access glyph_raster_grob Help

Source: https://rdrr.io/cran/systemfonts/src/R/font_outline.R

Opens the help documentation for the glyph_raster_grob function in the systemfonts package. This is useful for understanding the function's parameters and usage.

```R
library(systemfonts) help(glyph_raster_grob)
```

--------------------------------

### Match System Font by Name and Style

Source: https://rdrr.io/cran/systemfonts/src/R/match_fonts.R

Locates the best matching font file and index for a given name and optional style. Returns a font even if a perfect match isn't found, but it's not guaranteed to be similar. Aliases like 'sans', 'serif', 'mono' map to system defaults.

```R
match_fonts <- function(
  family,
  italic = FALSE,
  weight = "normal",
  width = "undefined"
) {
  if (!is.character(family) || anyNA(family))
    stop("`family` must be a character vector without NA values", call. = FALSE)
  weight <- as_font_weight(weight)
  width <- as_font_width(width)
  n_max <- max(length(family), length(italic), length(weight), length(width))
  locate_fonts_c(
    rep_len(family, n_max),
    rep_len(as.logical(italic), n_max),
    rep_len(weight, n_max),
    rep_len(width, n_max)
  )
}
```

--------------------------------

### Help for Font Squirrel Registry

Source: https://rdrr.io/cran/systemfonts/src/R/web_fonts.R

Displays the help documentation for the `get_font_squirrel_registry` function.

```R
library(systemfonts) help(get_font_squirrel_registry)
```

--------------------------------

### Get Google Fonts Registry (TTF)

Source: https://rdrr.io/cran/systemfonts/src/R/web_fonts.R

Retrieves the Google Fonts registry for TrueType fonts. The registry is cached for subsequent calls.

```R
google_fonts_registry <- new.env(parent = emptyenv())
get_google_fonts_registry <- function(woff2 = FALSE) {
  loc <- if (woff2) "woff2" else "ttf"
  if (is.null(google_fonts_registry[[loc]])) {
    url <- "https://www.googleapis.com/webfonts/v1/webfonts?key=AIzaSyBkOYsZREsyZWvbSR_d03SI5XX30cIapYo&sort=popularity"
    if (woff2) {
      url <- paste0(url, "&capability=WOFF2")
    }
    fonts <- jsonlite::read_json(url)$items
    google_fonts_registry[[loc]] <- do.call(
      rbind,
      lapply(fonts, function(x) {
        x <- data.frame(
          family = x$family,
          variant = unlist(x$variants),
          url = unlist(x$files),
          file = NA_character_,
          version = x$version,
          modified = x$lastModified,
          category = I(rep(list(x$category), length(x$variants)))
        )
        x$file <- paste0(
          x$family,
          "-",
          x$variant,
          sub("^.*(\.\w+)$", "\1", x$url)
        )
        attr(x, "row.names") <- .set_row_names(nrow(x))
        x
      })
    )
  }
  google_fonts_registry[[loc]]
}
```

--------------------------------

### Add Fonts from Files

Source: https://rdrr.io/cran/systemfonts/src/R/register_font.R

Adds fonts to the system by providing a list of file paths. It scans both the './fonts' and '~/fonts' directories recursively.

```R
files <- unique(c(
    list.files(
      "./fonts",
      all.files = TRUE,
      full.names = TRUE,
      recursive = TRUE
    ),
    list.files("~/fonts", all.files = TRUE, full.names = TRUE, recursive = TRUE)
  ))
  add_fonts(files)
```

--------------------------------

### Get Glyph Bitmap

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Retrieves a bitmap representation of a glyph. Requires glyph, path, index, size, resolution, color, and verbosity.

```R
get_glyph_bitmap <- function(glyph, path, index, size, res, color, verbose) {
  .Call(`_systemfonts_get_glyph_bitmap`, glyph, path, index, size, res, color, verbose)
}
```

--------------------------------

### Generate Web Font Import Specifications

Source: https://rdrr.io/cran/systemfonts/src/R/web_fonts.R

Creates stylesheet specifications for web fonts, supporting URL, @import, or <link> tag formats. It can fetch fonts from Google Fonts or Font Library, and optionally embed local fonts if they cannot be found.

```R
fonts_as_import <- function(
  family,
  italic = NULL,
  weight = NULL,
  width = NULL,
  ...,
  type = c("url", "import", "link"),
  may_embed = TRUE,
  repositories = c("Google Fonts", "Font Library")
) {
  import <- character(0)
  type <- match.arg(type)
  if (may_embed) repositories <- c(repositories, "local")

  for (repo in repositories) {
    fonts <- switch(
      tolower(repo),
      "google fonts" = import_from_google_fonts(
        family,
        italic = italic,
        weight = weight,
        width = width,
        ...
      ),
      "font library" = import_from_font_library(family, ...),
      "local" = import_embedded(
        family,
        italic = italic,
        weight = weight,
        width = width,
        ...
      ),
      NULL
    )
    if (!is.null(fonts)) {
      import <- c(import, fonts)
      missing <- attr(fonts, "no_match")

      family <- family[missing]
      if (!is.null(italic)) italic <- italic[missing]
      if (!is.null(width)) width <- width[missing]
      if (!is.null(weight)) weight <- weight[missing]
    }
    if (length(family) == 0) break
  }

  if (length(family) != 0) {

```

--------------------------------

### Shape Strings with Mixed Styles

Source: https://rdrr.io/cran/systemfonts/src/R/shape_string.R

Illustrates how to shape strings where different parts have varying text styles (e.g., font size). The `id` parameter groups strings that should be shaped together, and `size` allows specifying different font sizes for different string segments.

```R
string <- c(
  "This string will have\na ",
  "very large",
  " text style\nin the middle"
)

shape_string(string, id = c(1, 1, 1), size = c(12, 24, 12))
```

--------------------------------

### Match Font (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Finds the best matching system font based on family, italic, and bold properties. Returns font identifiers.

```R
match_font_c <- function(family, italic, bold) {
  .Call(`_systemfonts_match_font_c`, family, italic, bold)
}
```

--------------------------------

### Reset Font Cache - R

Source: https://rdrr.io/cran/systemfonts/man/reset_font_cache.html

Call reset_font_cache() to clear the system font cache. This ensures that newly installed fonts are recognized on the next call to functions like match_fonts().

```r
reset_font_cache()
```

--------------------------------

### Calculate String Widths (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Calculates the widths of strings using specified font properties. Requires font family, face, size, and unit.

```R
dev_string_widths_c <- function(string, family, face, size, cex, unit) {
  .Call(`_systemfonts_dev_string_widths_c`, string, family, face, size, cex, unit)
}
```

--------------------------------

### Get Number Tag

Source: https://rdrr.io/cran/systemfonts/src/R/font_feature.R

Converts a number setting name (e.g., 'lining', 'oldstyle') to its corresponding OpenType tag (e.g., 'lnum', 'onum'). Stops with an error if the name is not recognized.

```R
get_number_tag <- function(x) {
  name <- c(
    "lining",
    "oldstyle",
    "proportional",
    "tabular",
    "fractions",
    "fractions_alt"
  )
  tags <- c("lnum", "onum", "pnum", "tnum", "frac", "afrc")
  ind <- match(tolower(x), name)
  if (is.na(ind)) {
    stop(
      "No number setting called '",
      x,
      "'. Use one of ",
      paste(name, collapse = ", "),
      call. = FALSE
    )
  }
  tags[ind]
}
```

--------------------------------

### string_metrics_dev

Source: https://rdrr.io/cran/systemfonts/man/string_metrics_dev.html

This function is much like `string_widths_dev()` but also returns the ascent and descent of the string making it possible to construct a tight bounding box around the string.

```APIDOC
## string_metrics_dev

### Description
This function is much like `string_widths_dev()` but also returns the ascent and descent of the string making it possible to construct a tight bounding box around the string. 

### Usage
```R
string_metrics_dev(
  strings,
  family = "",
  face = 1,
  size = 12,
  cex = 1,
  unit = "cm"
)

```

### Arguments
`strings` |  A character vector of strings to measure  
`family` |  The font families to use. Will get recycled  
`face` |  The font faces to use. Will get recycled  
`size` |  The font size to use. Will get recycled  
`cex` |  The cex multiplier to use. Will get recycled  
`unit` |  The unit to return the width in. Either `"cm"`, `"inches"`, `"device"`, or `"relative"`  

### Value
A data.frame with `width`, `ascent`, and `descent` columns giving the metrics in the requested unit. 

### See Also
Other device metrics: `string_widths_dev()`

### Examples
```R
# Get the metrics as measured in cm (default)
string_metrics_dev(c('some text', 'a string with descenders'))

```
```

--------------------------------

### Get Ligature Tag

Source: https://rdrr.io/cran/systemfonts/src/R/font_feature.R

Converts a ligature setting name (e.g., 'standard', 'historical') to its corresponding OpenType tag (e.g., 'liga', 'hlig'). Stops with an error if the name is not recognized.

```R
get_ligature_tag <- function(x) {
  name <- c("standard", "historical", "contextual", "discretionary")
  tags <- c("liga", "hlig", "clig", "dlig")
  ind <- match(tolower(x), name)
  if (is.na(ind)) {
    stop(
      "No ligature setting called '",
      x,
      "'. Use one of ",
      paste(name, collapse = ", "),
      call. = FALSE
    )
  }
  tags[ind]
}
```

--------------------------------

### reset_font_cache

Source: https://rdrr.io/cran/systemfonts/man/reset_font_cache.html

Resets the system font cache. After calling this function, the next invocation of font matching functions (e.g., `match_fonts()`) will rebuild the cache, incorporating any newly installed system fonts.

```APIDOC
## reset_font_cache

### Description
Building the list of system fonts is time consuming and is therefore cached. This, in turn, means that changes to the system fonts (i.e. installing new fonts), will not propagate to systemfonts. The solution is to reset the cache, which will result in the next call to e.g. `match_fonts()` will trigger a rebuild of the cache.

### Usage
```R
reset_font_cache()
```

### Examples
```R
# Get initial list of fonts
all_fonts <- system_fonts()

# Simulate installing a new font (conceptually)
# ... install font on system ...

# Get font list again - it should be the same before cache reset
all_fonts_new <- system_fonts()

# Reset the font cache
reset_font_cache()

# Get font list again - it should now include the new font
all_fonts_new <- system_fonts()
```
```

--------------------------------

### Import Fonts from Google Fonts

Source: https://rdrr.io/cran/systemfonts/src/R/web_fonts.R

Generates a URL to import fonts from Google Fonts, supporting various styles and weights. Handles missing fonts and allows custom text display.

```R
import_from_google_fonts <- function(
  family,
  italic = NULL,
  weight = NULL,
  width = NULL,
  ...,
  text = NULL,
  display = "swap"
) {
  n_fonts <- max(length(family), length(italic), length(weight), length(width))
  family <- rep_len(family, n_fonts)
  if (!is.null(italic)) italic <- rep_len(as.integer(italic), n_fonts)
  if (!is.null(weight))
    weight <- rep_len(systemfonts::as_font_weight(weight), n_fonts)
  if (!is.null(width))
    width <- rep_len(systemfonts::as_font_width(width), n_fonts)

  clusters <- split(seq_along(family), family)

  possible_fonts <- unique(get_google_fonts_registry()$family)

  fonts <- lapply(clusters, function(i) {
    fam <- family[i[1]]
    fam <- match(tolower(fam), tolower(possible_fonts))
    if (is.na(fam)) return()
    fam <- possible_fonts[fam]
    fam <- paste0("family=", gsub(" ", "+", family[i[1]]))

    spec <- list()
    spec$ital <- if (!is.null(italic)) unique(range(italic[i]))
    if (isTRUE(spec$ital == 0L)) spec$ital <- NULL
    spec$wdth <- if (!is.null(width))
      paste0(unique(range(width[i])), collapse = "..")
    spec$wght <- if (!is.null(weight))
      paste0(unique(range(weight[i])), collapse = "..")
    spec <- spec[lengths(spec) != 0]
    if (length(spec) != 0) {
      spec$sep <- ","
      val <- paste0(do.call(paste0, spec), collapse = ";")
      spec <- paste0(names(spec), collapse = ",")
      fam <- paste0(fam, ":", spec, "@", val)
    }
    fam
  })
  missing <- unlist(clusters[lengths(fonts) == 0]) %||% integer()
  fonts <- paste0(unlist(fonts), collapse = "&")

  display <- match.arg(
    display,
    c("auto", "block", "swap", "fallback", "optional")
  )

  url <- paste0("https://fonts.googleapis.com/css2?", fonts)

  if (display != "auto") {
    url <- paste0(url, "&display=", display)
  }

  if (!is.null(text)) {
    url <- paste0(url, "&text=", utils::URLencode(text))
  }

  success <- try(suppressWarnings(readLines(url, n = 1)), silent = TRUE)
  if (inherits(success, "try-error")) {
    url <- character(0)
    missing <- seq_along(family)
  }
  structure(url %||% character(), no_match = missing)
}
```

--------------------------------

### system_fonts_c

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Retrieves a list of all fonts available on the system.

```APIDOC
## system_fonts_c

### Description
Retrieves a list of all fonts available on the system.
```

--------------------------------

### Get string widths using string_widths_dev

Source: https://rdrr.io/cran/systemfonts/man/string_widths_dev.html

Measures the width of strings using the default unit of centimeters. This function provides direct access to the graphic device for efficient string width calculation.

```R
string_widths_dev(
  strings,
  family = "",
  face = 1,
  size = 12,
  cex = 1,
  unit = "cm"
)


```

```R
# Get the widths as measured in cm (default)
string_widths_dev(c('a string', 'an even longer string'))


```

--------------------------------

### Shape String with Default Settings

Source: https://rdrr.io/cran/systemfonts/man/shape_string.html

Use shape_string with default parameters to shape a multi-line string.

```R
string <- "This is a long string\nLook; It spans multiple lines\nand all"

# Shape with default settings
shape_string(string)
```

--------------------------------

### Filter Monospace Fonts

Source: https://rdrr.io/cran/systemfonts/man/system_fonts.html

After retrieving all system fonts, you can filter the resulting data frame to find specific types of fonts, such as monospace fonts. This example shows how to select rows where the 'monospace' column is TRUE.

```R
# See all monospace fonts
fonts <- system_fonts()
fonts[fonts$monospace, ]
```

--------------------------------

### Get Glyph Outline Coordinates

Source: https://rdrr.io/cran/systemfonts/src/R/font_outline.R

Retrieve the outline of glyphs as polygon coordinates. Glyphs are specified by index into a font file. Bitmapped glyphs are ignored. Use this when you need vector data for glyph shapes.

```R
glyph_outline <- function(
  glyph,
  path,
  index = 0,
  size = 12,
  tolerance = 0.2,
  verbose = FALSE
) {
  n_glyphs <- length(glyph)
  glyph <- as.integer(glyph)
  path <- rep_len(as.character(path), n_glyphs)
  index <- rep_len(as.integer(index), n_glyphs)
  size <- rep_len(as.numeric(size), n_glyphs)
  tolerance <- as.numeric(tolerance)

  get_glyph_outlines(glyph, path, index, size, tolerance, verbose)
}
```

--------------------------------

### Download Font from Font Squirrel

Source: https://rdrr.io/cran/systemfonts/src/R/web_fonts.R

Downloads a specified font family from Font Squirrel, unzips it, and adds the font files to the local directory. Returns invisibly TRUE if successful, FALSE otherwise.

```R
get_from_font_squirrel <- function(family, dir = "~/fonts") {
  fonts <- get_font_squirrel_registry()
  match <- which(tolower(fonts$family) == tolower(family))

  if (length(match) == 0) {
    return(invisible(FALSE))
  }

  if (!dir.exists(dir)) dir.create(dir, recursive = TRUE)

  files <- fonts$url[match]
  download_name <- file.path(
    tempdir(check = TRUE),
    paste0(basename(fonts$url[match]), ".zip")
  )
  success <- try(
    {
      if (capabilities("libcurl")) {
        utils::download.file(files, download_name, method = "libcurl")
      } else {
        mapply(utils::download.file, url = files, destfile = download_name)
      }
    },
    silent = TRUE
  )

  if (inherits(success, "try-error")) {
    return(invisible(FALSE))
  }

  new_fonts <- unlist(mapply(
    utils::unzip,
    zipfile = download_name,
    MoreArgs = list(exdir = dir)
  ))
  is_font <- grepl("\.(?:ttf|ttc|otf|otc|woff|woff2)$", tolower(new_fonts))
  unlink(new_fonts[!is_font])
  add_fonts(new_fonts[is_font])

  return(invisible(TRUE))
}
```

--------------------------------

### Locate Fonts (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Locates system fonts matching specified criteria like family, italic, weight, and width. Returns font paths.

```R
locate_fonts_c <- function(family, italic, weight, width) {
  .Call(`_systemfonts_locate_fonts_c`, family, italic, weight, width)
}
```

--------------------------------

### Shape String (C++11)

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Shapes a string for rendering, considering various layout parameters like line height, alignment, and tracking. Uses font ID and path.

```R
get_string_shape_c <- function(string, id, path, index, size, res, lineheight, align, hjust, vjust, width, tracking, indent, hanging, space_before, space_after) {
  .Call(`_systemfonts_get_string_shape_c`, string, id, path, index, size, res, lineheight, align, hjust, vjust, width, tracking, indent, hanging, space_before, space_after)
}
```

--------------------------------

### Add Local Fonts

Source: https://rdrr.io/cran/systemfonts/src/R/cpp11.R

Registers local font files to be used by the systemfonts package. Takes a vector of file paths.

```R
add_local_fonts <- function(paths) {
  .Call(`_systemfonts_add_local_fonts`, paths)
}
```

--------------------------------

### Reset System Font Cache in R

Source: https://rdrr.io/cran/systemfonts/src/R/system_fonts.R

Use this function to clear the cached list of system fonts. This is necessary after installing new fonts on your system to ensure that the systemfonts package recognizes the changes. The cache will be rebuilt on the next call to functions like `match_fonts()`.

```R
reset_font_cache <- function() {
  reset_font_cache_c()
}
```

```R
all_fonts <- system_fonts()

##-- Install a new font on the system --##

all_fonts_new <- system_fonts()

## all_fonts_new will be equal to all_fonts

reset_font_cache()

all_fonts_new <- system_fonts()

## all_fonts_new will now contain the new font
```

--------------------------------

### Import Fonts from Font Library

Source: https://rdrr.io/cran/systemfonts/src/R/web_fonts.R

Fetches font URLs from Font Library based on family names. Returns available font URLs and identifies missing ones.

```R
import_from_font_library <- function(family, ...) {
  family <- gsub(" ", "-", tolower(family))
  u_fam <- unique(family)
  names(u_fam) <- u_fam
  fonts <- lapply(u_fam, function(name) {
    url <- paste0("https://fontlibrary.org/face/", name)
    if (length(readLines(url, n = 1)) != 0) {
      url
    } else {
      NULL
    }
  })
  missing <- which(family %in% names(fonts[lengths(fonts) == 0]))
  fonts <- unlist(fonts)

  structure(fonts %||% character(), no_match = missing, names = NULL)
}
```
Tokens:
Raw