Custom guide

[teunbrand]

This PR aims to fix #5416.

Briefly, it introduces guide_custom() for drawing arbitrary grobs alongside regular legends.

In some more detail:

• It required new plumbing in Guides$build() because these guides don't have associated scales that train them (nor should they, but the assumption was that there is a scale associated to a guide).
• Guide itself is essentially building a gtable around the grob with legend margins and a title.

A demonstration:

devtools::load_all("~/packages/ggplot2")
#> ℹ Loading ggplot2

# Making a grob
n <- 5
t <- seq(0, 2 * pi, length.out = n * 2 + 1)[-(n * 2 + 1)]
l <- rep(c(1, 0.4), length.out = length(t))
x <- cos(t) * l
y <- sin(t) * l
mid <- unit(0.5, "npc")
grob <- polygonGrob(x = unit(x, "cm") + mid, y = unit(y, "cm") + mid)

# Displaying grob as guide
ggplot(mpg, aes(displ, hwy, colour = factor(cyl))) +
  geom_point() +
  guides(foo = guide_custom(grob, title = "star"))

I also realised that it makes it easy to make inset plots with this guide, as you can just pass a rendered plot as the grob.

p <- ggplot(mpg, aes(class, displ)) + geom_boxplot()

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  guides(foo = guide_custom(
    ggplotGrob(p), title = "inset plot",
    width = unit(6, "cm"), height = unit(4, "cm")
  )) +
  theme(legend.position = c(1, 1), legend.justification = c(1, 1),
        legend.background = element_blank())

^{Created on 2023-10-26 with reprex v2.0.2}

[thomasp85]

While possible I don't think we should advocate the latter use as it muddies the whole guide concept

[teunbrand]

Yeah agreed, but I don't think we should disallow it either because it has some use-cases. One of them is if you plot a map of a country and you'd want to display the world as a guide, highlighting the country.

[teunbrand]

Adapted the PR to plumbing in #5483

[thomasp85]

Can you elaborate on this change?

[teunbrand]

Sure, in the absence of non-position (NP) scales, we still want to render the custom guides.
Previously, if there were no NP scales, there'd be no need to render any NP guides, so we could set the guides list to empty (as position guides have been absorbed already by the coord).
However, since custom guides aren't attached to a scale, setting the guides list to empty would also discard the custom guides. Instead, we extract only the custom guides if there are no NP scales. In absence of any custom guides, the plot$guides$get_custom() just returns an empty guides list.