textpathGrob {geomtextpath}

Draw text on a path.

Description

This function creates (curved) text on a path.

Usage

textpathGrob(
  label,
  x = 0.5,
  y = 0.5,
  id = 1L,
  just = "centre",
  hjust = NULL,
  vjust = NULL,
  halign = "left",
  angle = 0,
  straight = FALSE,
  rich = FALSE,
  gp_text = gpar(),
  gp_path = gpar(),
  gp_box = gpar(),
  gap = NA,
  upright = TRUE,
  text_smoothing = 0,
  polar_params = NULL,
  padding = unit(0.05, "inch"),
  label.padding = unit(0.25, "lines"),
  label.r = unit(0.15, "lines"),
  remove_long = FALSE,
  arrow = NULL,
  default.units = "npc",
  name = NULL,
  vp = NULL,
  as_label = FALSE
)

Arguments

label

A character vector.

x

A numeric vector.

y

A numeric vector.

id

A numeric vector used to separate locations in x and y into multiple lines. All locations with the same id belong to the same line.

just

The justification of the text relative to its (x, y) location. If there are two values, the first value specifies horizontal justification and the second value specifies vertical justification. Possible string values are: "left", "right", "centre", "center", "bottom", and "top". For numeric values, 0 means left (bottom) alignment and 1 means right (top) alignment.

hjust

A numeric vector specifying horizontal justification. If specified, overrides the just setting.

vjust

A numeric vector specifying justification orthogonal to the direction of the text. Alternatively a unit() object to directly set the offset from the path.

halign

A character(1) describing how multi-line text should be justified. Can either be "center" (default), "left" or "right".

angle

a numeric vector either length 1 or the same length as id describing the angle in degrees at which text should be rotated.

straight

A logical(1) which if TRUE, keeps the letters of a label on a straight baseline and if FALSE (default), lets individual letters follow the curve. This might be helpful for noisy paths.

rich

A logical(1) whether to interpret the text as html/markdown formatted rich text. Default: FALSE. See also the rich text section of the details in geom_textpath().

gp_text, gp_path

An object of class "gpar", typically the output from a call from the gpar() function. These are basically lists of graphical parameters for the text and path respectively.

gp_box

(Optional) an object of class "gpar", typically the output from a call to the gpar() function. If this is an empty list, no text box will be drawn.

gap

A logical(1) which if TRUE, breaks the path into two sections with a gap on either side of the label. If FALSE, the path is plotted as a whole. Alternatively, if NA, the path will be broken if the string has a vjust between 0 and 1, and not otherwise. The default for the label variant is FALSE and for the text variant is NA.

upright

A logical(1) which if TRUE (default), inverts any text where the majority of letters would upside down along the path, to improve legibility. If FALSE, the path decides the orientation of text.

text_smoothing

a numeric(1) value between 0 and 100 that smooths the text without affecting the line portion of the geom. The default value of 0 means no smoothing is applied.

polar_params

a list consisting of an x, y, and r component that specifies the central point and radius of a circle around which single-point labels will be wrapped.

padding

A unit object of length 1 to determine the padding between the text and the path when the gap parameter trims the path.

label.padding

Amount of padding around label. Defaults to 0.25 lines.

label.r

Radius of rounded corners. Defaults to 0.15 lines.

remove_long

if TRUE, labels that are longer than their associated path will be removed.

arrow

Arrow specification, as created by arrow().

default.units

A string indicating the default units to use if x or y are only given as numeric vectors.

name

A character identifier.

vp

A Grid viewport object (or NULL).

as_label

a logical TRUE or FALSE indicating whether the text should be drawn inside a text box. If FALSE, the parameters label.padding, label.r and gp_box will be ignored.

Value

An object of class gTree, containing grobs.

Examples

require(grid)

t <- seq(0, 2 * pi, length.out = 100)
grob <- textpathGrob(
  label = c(
    "Why I am making trigonometry jokes? Cos I can!",
    "I was never any good at sine language."
  ),
  x = c(t, t) / (2 * pi),
  y = c(cos(t), sin(t)) * 0.25 + 0.5,
  id = rep(1:2, each = length(t)),
  vjust = rep(0.5, 2 * length(t)),
  gp_text = gpar(lineheight = c(1.2, 1.2), fontsize = c(10, 10)),
  gp_path = gpar(lty = c(1, 2))
)

grid.newpage(); grid.draw(grob)