ggfittext (version 0.6.0)

geom_fit_text: A 'ggplot2' geom to fit text inside a box

Description

geom_fit_text shrinks, grows or wraps text to fit inside a defined rectangular area.

Usage

geom_fit_text(mapping = NULL, data = NULL, stat = "identity",
  position = "identity", na.rm = FALSE, show.legend = NA,
  inherit.aes = TRUE, padding.x = grid::unit(1, "mm"),
  padding.y = grid::unit(0.1, "lines"), place = "centre", min.size = 4,
  grow = FALSE, reflow = FALSE, width = grid::unit(40, "mm"),
  height = grid::unit(40, "mm"), ...)

Arguments

mapping

ggplot2::aes() object as standard in 'ggplot2'. Note that aesthetics specifying the box must be provided. See Details.

data, stat, position, na.rm, show.legend, inherit.aes, ...

Standard geom arguments as for ggplot2::geom_text().

padding.x, padding.y

Amount of horizontal and vertical padding around the text, expressed as grid::unit() objects. Default to 1 mm and 0.1 lines respectively.

place

Where inside the box to place the text. Default is 'centre'; other options are 'topleft', 'top', 'topright', etc.

min.size

Minimum font size, in points. If provided, text that would need to be shrunk below this size to fit the box will not be drawn. Defaults to 4 pt.

grow

If 'TRUE', text will be grown as well as shrunk to fill the box. See Details.

reflow

If 'TRUE', text will be reflowed (wrapped) to better fit the box. See Details.

width, height

When using `x` and/or `y` aesthetics, these will be used to determine the width and/or height of the box. These should be either numeric values on the x and y scales or grid::unit() objects. Both default to 40 mm units.

Aesthetics

• label (required)

• xmin, xmax OR x (required)

• ymin, ymax OR y (required)

• alpha

• angle

• colour

• family

• fontface

• lineheight

• size

Details

Except where noted, geom_fit_text behaves more or less like ggplot2::geom_text.

In addition to the normal geom_text aesthetics, geom_fit_text requires you to specify the box in which you wish to fit the text, usually with 'xmin', 'xmax', 'ymin' and 'ymax' aesthetics. Alternatively, you can specify the centre of the box with 'x' and/or 'y', and the height and/or width of the box with 'height' and/or 'width' arguments. This can be useful when one or both axes are discrete. 'height' and 'width' should be provided as `grid::unit()` objects, and both default to 40 mm.

By default, the text will be drawn as if with geom_text, unless it is too big for the box, in which case it will be shrunk to fit the box. With grow = TRUE, the text will be made to fill the box completely whether that requires shrinking or growing.

reflow = TRUE will cause the text to be reflowed (wrapped) to better fit in the box. When grow = FALSE (default), text that fits the box will be drawn as if with geom_text; text that doesn't fit the box will be reflowed until it does. If the text cannot be made to fit by reflowing alone, it will be reflowed to match the aspect ratio of the box as closely as possible, then be shrunk to fit the box. When grow = TRUE, the text will be reflowed to best match the aspect ratio of the box, then made to fill the box completely whether that requires growing or shrinking. Existing line breaks ('\n') in the text will be respected when reflowing.

Examples

# NOT RUN {
ggplot2::ggplot(ggplot2::presidential, ggplot2::aes(ymin = start, ymax = end,
    label = name, fill = party, xmin = 0, xmax = 1)) +
  ggplot2::geom_rect(colour = 'black') +
  geom_fit_text(grow = TRUE)

# }