Skip to contents

Draw text with shadow border

Usage

shadowText(
  x,
  y = NULL,
  labels = NULL,
  col = "white",
  bg = NULL,
  shadowColor = getOption("jam.shadowColor", "black"),
  r = getOption("jam.shadow.r", 0.1),
  offset = c(0.15, -0.15),
  n = getOption("jam.shadow.n", 16),
  outline = getOption("jam.outline", TRUE),
  alphaOutline = getOption("jam.alphaOutline", 0.4),
  shadow = getOption("jam.shadow", FALSE),
  alphaShadow = getOption("jam.alphaShadow", 0.07),
  shadowOrder = c("each", "all"),
  cex = graphics::par("cex"),
  shadowCex = 1,
  font = graphics::par("font"),
  doTest = FALSE,
  ...
)

Arguments

x, y

numeric coordinates, either as vectors x and y, or x as a two-color matrix recognized by grDevices::xy.coords().

labels

character labels to display at the corresponding xy coordinates.

col, bg, shadowColor

the label color, and background (outline) color, and shadow color, respectively. Each vector is recycled to length(labels).

  • col defines the text color.

  • bg defines the outline color, when 'outline=TRUE', and default bg=NULL will use setTextContrast() to use contrasting white or black.

  • shadowColor uses option 'jam.shadowColor' and default 'black', since a shadow typically always adds darkness. It can be a light color, which has the effect of under-lighting.

r

numeric outline radius, expressed as a fraction of the width of character "A" returned by graphics::strwidth().

offset

numeric shadow offset position in xy coordinates, as a fraction of the width of the character "A" returned by graphics::strwidth(), and graphics::strheight(), respectively. Two values are applied to x, and y, respectively.

n

numeric steps around the label used to create the outline. A higher number may be useful for very large font sizes, otherwise 8 is a reasonably good balance between detail and the number of labels added.

outline

logical whether to enable outline drawing.

alphaOutline, alphaShadow

numeric alpha transparency to use for the outline and shadow colors, respectively.

shadow

logical whether to enable shadow drawing.

shadowOrder

character value indicating when shadows are drawn relative to drawing labels:

  • "each" draws each shadow with each label, so each label has its own direct shadow. Labels that overlap are distinct with independent shadow.

  • "all" draws all shadows first then all labels. Labels always appear above all shadows, and tend to join together when they overlap.

cex

numeric scalar applied to font size, default graphics::par("cex").

shadowCex

numeric to adjust shadow size relative to the outline size. It affects the radius 'r', and adjusts the 'offset' by half the 'shadowCex'.

font

character applied to font family, default graphics::par("font"). Use 'font=2' for bold text.

doTest

logical whether to create a visual example of output. Note that it calls usrBox() to color the plot area, and the background can be overridden with something like 'fill="navy"'.

...

other parameters are passed to graphics::text(). Note that certain parameters are not vectorized in that function, such as 'srt' which requires only a fixed value. To rotate each label independently, multiple calls to graphics::text() or shadowText() must be made. Other parameters like adj only accept up to two values, and those two values affect all label positioning.

Value

invisible list of components used to call graphics::text(), including: x, y, allColors, allLabels, cex, font.

Details

Draws text with the same syntax as graphics::text() except that this function adds a contrasting color border around the text, which helps visibility when the background color is either not known, or is not expected to be a fixed contrasting color.

The function draws the label n times with the chosed background color, then the label itself atop the background text. It does not typically have a noticeable effect on rendering time, but it may impact downstream uses in vector file formats like 'SVG' and 'PDF', where text is stored as proper text and font objects. Take care when editing text that the underlying shadow text is also edited in sync.

The parameter doTest=TRUE will display a visual example. The background color can be modified with fill="navy" for example.

Examples

shadowText(doTest=TRUE);

shadowText(doTest=TRUE, fill="navy");


# example showing labels with overlapping shadows
withr::with_par(list("mfrow"=c(1, 2)), {
nullPlot(doBoxes=FALSE);
graphics::title(main="shadowOrder='each'");
shadowText(x=c(1.5, 1.65), y=c(1.5, 1.55),
   labels=c("one", "two"), cex=c(2, 4), shadowOrder="each")
nullPlot(doBoxes=FALSE);
graphics::title(main="shadowOrder='all'");
shadowText(x=c(1.5, 1.65), y=c(1.5, 1.55),
   labels=c("one", "two"), cex=c(2, 4), shadowOrder="all")
})