Learn R Programming

gdtools (version 0.6.0)

strings_sizes: 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 the metrics stored in the font file are read with FreeType, without scaling or hinting:

  • the width is the sum of the glyph advances; with kerning = TRUE, the kerning between consecutive glyphs is added (see below);

  • the ascent and the descent are those of the box enclosing the ink of the glyphs, so they depend on the text ("xxx" has no descent).

The results only depend on the font file: the same file gives the same values on every platform. They are accurate for devices whose rendering finds the same font -- this is guaranteed for 'systemfonts'-based devices (ragg, svglite, ggiraph) and true for 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.

When the font file found cannot be read, a warning is issued and the default sans-serif font is used. NA strings give NA metrics; invalid UTF-8 strings are measured as empty strings.

Usage

strings_sizes(
  x,
  fontname = "sans",
  fontsize = 10,
  bold = FALSE,
  italic = FALSE,
  kerning = 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.

kerning

If TRUE, the width includes the kerning stored in the font file, as devices that kern when drawing (ragg, svglite, ggiraph, cairo_pdf()). Default is FALSE, the width is then the sum of the glyph advances. A single logical value.

Kerning

Kerning adjusts the space between some pairs of glyphs (for example "AV" or "To"). With kerning = TRUE, the adjustments are read from the tables of the font file and added to the width, without text shaping:

  • a single table is used: 'kerx' when the font has one, otherwise 'GPOS' when it has a 'kern' feature, otherwise the 'kern' table;

  • in 'GPOS', the lookups of the 'kern' feature for the script of the text are used; the script (Latin, Greek or Cyrillic) is guessed from the first letter of the string, other strings use the default script;

  • adjustments of single glyphs and of pairs of glyphs are applied; contextual kerning is not;

  • ligatures and other glyph substitutions are not applied, so the width of a string such as "office" may differ from the drawn text with fonts that substitute glyphs by default;

  • right-to-left and complex scripts are not shaped.

See Also

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

Examples

Run this code
strings_sizes(letters)
strings_sizes("AVATAR", fontsize = 12)$width
strings_sizes("AVATAR", fontsize = 12, kerning = TRUE)$width
strings_sizes("Hello World!", bold = TRUE, italic = FALSE,
  fontname = "sans", fontsize = 12)

Run the code above in your browser using DataLab