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
numericcoordinates, either as vectors x and y, or x as a two-color matrix recognized bygrDevices::xy.coords().- labels
characterlabels 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
numericoutline radius, expressed as a fraction of the width of character "A" returned bygraphics::strwidth().- offset
numericshadow offset position in xy coordinates, as a fraction of the width of the character "A" returned bygraphics::strwidth(), andgraphics::strheight(), respectively. Two values are applied to x, and y, respectively.- n
numericsteps 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
logicalwhether to enable outline drawing.- alphaOutline, alphaShadow
numericalpha transparency to use for the outline and shadow colors, respectively.- shadow
logicalwhether to enable shadow drawing.- shadowOrder
charactervalue 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
numericscalar applied to font size, defaultgraphics::par("cex").- shadowCex
numericto adjust shadow size relative to the outline size. It affects the radius 'r', and adjusts the 'offset' by half the 'shadowCex'.- font
characterapplied to font family, defaultgraphics::par("font"). Use 'font=2' for bold text.- doTest
logicalwhether to create a visual example of output. Note that it callsusrBox()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 tographics::text()orshadowText()must be made. Other parameters likeadjonly 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.
See also
Other jam plot functions:
adjustAxisLabelMargins(),
coordPresets(),
decideMfrow(),
drawLabels(),
getPlotAspect(),
groupedAxis(),
imageByColors(),
imageDefault(),
minorLogTicksAxis(),
nullPlot(),
plotPolygonDensity(),
plotRidges(),
plotSmoothScatter(),
shadowText_options(),
showColors(),
sqrtAxis(),
usrBox()
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")
})