shape_string: Calculate glyph positions for strings

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

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
)

Value

A list with two element: 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: The glyph as a character
index: The index of the glyph in the font file
metric_id: The index of the string the glyph is part of (referencing a row in the metrics data.frame)
string_id: The index of the string the glyph came from (referencing an element in the strings input)
x_offset: The x offset in pixels from the origin of the textbox
y_offset: The y offset in pixels from the origin of the textbox
x_mid: 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: The text the string consist of
width: The width of the string
height: The height of the string
left_bearing: The distance from the left edge of the textbox and the leftmost glyph
right_bearing: The distance from the right edge of the textbox and the rightmost glyph
top_bearing: The distance from the top edge of the textbox and the topmost glyph
bottom_bearing: The distance from the bottom edge of the textbox and the bottommost glyph
left_border: The position of the leftmost edge of the textbox related to the origin
top_border: The position of the topmost edge of the textbox related to the origin
pen_x: The horizontal position of the next glyph after the string
pen_y: The vertical position of the next glyph after the string

Arguments

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

Examples

Run this code

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

Run the code above in your browser using DataLab