Performs advanced text shaping of strings including font fallbacks, bidirectional script support, word wrapping and various character and paragraph level formatting settings.
Usage
shape_text(
strings,
id = NULL,
family = "",
italic = FALSE,
weight = "normal",
width = "undefined",
features = font_feature(),
size = 12,
res = 72,
lineheight = 1,
align = "auto",
hjust = 0,
vjust = 0,
max_width = NA,
tracking = 0,
indent = 0,
hanging = 0,
space_before = 0,
space_after = 0,
direction = "auto",
path = NULL,
index = 0,
bold = deprecated()
)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
- weight
The weight to query for, either in numbers (
0,100,200,300,400,500,600,700,800, or900) or strings ("undefined","thin","ultralight","light","normal","medium","semibold","bold","ultrabold", or"heavy").NAwill be interpreted as"undefined"/0- width
The width to query for either in numbers (
0,1,2,3,4,5,6,7,8, or9) or strings ("undefined","ultracondensed","extracondensed","condensed","semicondensed","normal","semiexpanded","expanded","extraexpanded", or"ultraexpanded").NAwill be interpreted as"undefined"/0- features
A
systemfonts::font_feature()object or a list of them, giving the OpenType font features to set- size
The size in points to use for the font
- res
The resolution to use when doing the shaping. Should optimally match the resolution used when rendering the glyphs.
- lineheight
A multiplier for the lineheight
- align
Within text box alignment, either
'auto','left','center','right','justified','justified-left','justified-right','justified-center', or'distributed'.'auto'and'justified'will chose the left or right version depending on the direction of the text.- hjust, vjust
The justification of the textbox surrounding the text
- max_width
The requested with of the string in inches. Setting this to something other than
NAwill 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
- direction
The overall directional flow of the text. The default (
"auto") will guess the direction based on the content of the string. Use"ltr"(left-to-right) and"rtl"(right-to-left) to turn detection of and set it manually.- path, index
path an index of a font file to circumvent lookup based on family and style
- bold
logical indicating whether the font weight
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 placement of the the first character contributing to the glyph within the string
- 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
metricsdata.frame)- string_id
The index of the string the glyph came from (referencing an element in the
stringsinput)- 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
- font_path
The path to the font file used during shaping of the glyph
- font_index
The index of the font used to shape the glyph in the font file
- font_size
The size of the font used during shaping
- advance
The advancement amount to the next glyph
- ascender
The ascend of the font used for the glyph. This does not measure the actual glyph
- descender
The descend of the font used for the glyph. This does not measure the actual 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
- ltr
The global direction of the string. If
TRUEthen it is left-to-right, otherwise it is right-to-left
Examples
string <- "This is a long string\nLook; It spans multiple lines\nand all"
# Shape with default settings
shape_text(string)
#> $shape
#> # A tibble: 57 × 12
#> glyph index metric_id string_id x_offset y_offset font_path font_index
#> <int> <int> <int> <int> <dbl> <dbl> <chr> <int>
#> 1 1 55 1 1 0 36.2 /usr/share/font… 0
#> 2 2 75 1 1 6.67 36.2 /usr/share/font… 0
#> 3 3 76 1 1 14.1 36.2 /usr/share/font… 0
#> 4 4 86 1 1 17.2 36.2 /usr/share/font… 0
#> 5 5 3 1 1 22.9 36.2 /usr/share/font… 0
#> 6 6 76 1 1 26.1 36.2 /usr/share/font… 0
#> 7 7 86 1 1 29.2 36.2 /usr/share/font… 0
#> 8 8 3 1 1 34.9 36.2 /usr/share/font… 0
#> 9 9 68 1 1 38.0 36.2 /usr/share/font… 0
#> 10 10 3 1 1 44.8 36.2 /usr/share/font… 0
#> # ℹ 47 more rows
#> # ℹ 4 more variables: font_size <dbl>, advance <dbl>, ascender <dbl>,
#> # descender <dbl>
#>
#> $metrics
#> # A tibble: 1 × 12
#> string width height left_bearing right_bearing top_bearing bottom_bearing
#> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
#> 1 "This is a… 157. 49.0 0.125 0.547 3.70 3.39
#> # ℹ 5 more variables: left_border <dbl>, top_border <dbl>, pen_x <dbl>,
#> # pen_y <dbl>, ltr <lgl>
#>
# Mix styles within the same string
string <- c(
"This string will have\na ",
"very large",
" text style\nin the middle"
)
shape_text(string, id = c(1, 1, 1), size = c(12, 24, 12))
#> $shape
#> # A tibble: 57 × 12
#> glyph index metric_id string_id x_offset y_offset font_path font_index
#> <int> <int> <int> <int> <dbl> <dbl> <chr> <int>
#> 1 1 55 1 1 0 56.1 /usr/share/font… 0
#> 2 2 75 1 1 6.67 56.1 /usr/share/font… 0
#> 3 3 76 1 1 14.1 56.1 /usr/share/font… 0
#> 4 4 86 1 1 17.2 56.1 /usr/share/font… 0
#> 5 5 3 1 1 22.9 56.1 /usr/share/font… 0
#> 6 6 86 1 1 26.1 56.1 /usr/share/font… 0
#> 7 7 87 1 1 31.8 56.1 /usr/share/font… 0
#> 8 8 85 1 1 36.1 56.1 /usr/share/font… 0
#> 9 9 76 1 1 41.1 56.1 /usr/share/font… 0
#> 10 10 81 1 1 44.2 56.1 /usr/share/font… 0
#> # ℹ 47 more rows
#> # ℹ 4 more variables: font_size <dbl>, advance <dbl>, ascender <dbl>,
#> # descender <dbl>
#>
#> $metrics
#> # A tibble: 1 × 12
#> string width height left_bearing right_bearing top_bearing bottom_bearing
#> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
#> 1 "This stri… 175. 68.9 0.125 0.609 3.70 6.91
#> # ℹ 5 more variables: left_border <dbl>, top_border <dbl>, pen_x <dbl>,
#> # pen_y <dbl>, ltr <lgl>
#>