Hi @Nowosad and @Robinlovelace

I've implemented tm_title and should be backwards compatible with v3:

tm_shape(World) + tm_polygons("HPI") + tm_title("Test")

tm_shape(World) + tm_polygons("HPI") + tm_title_in("Test")

tm_shape(World) + tm_polygons(c("HPI", "economy")) + tm_title_in("Test")

tm_shape(World) + tm_polygons(c("HPI", "economy")) + tm_title_in(c("TestA", "TestB")) + tm_title("TestC")

tm_shape(World) + tm_polygons(c("HPI", "economy")) + tm_title(c("TestA", "TestB"))

tm_shape(World) + tm_polygons(c("HPI", "economy")) + tm_layout(title = c("TestA", "TestB"), main.title = "TestC")

I made a choice on the function names, but this is open for discussion. In tmap3, there was "title" which was used as in-frame title, and "main.title", used as out-frame title.

The only reason the latter was called 'main' is that for facets, title can be set per facet, whereas main.title is the overarching title. However, historically, title and main.titles have been implemented before panel labels. Now it makes more sense to use panel labels for facets. In fact, that is also the default when facets are produced (also in v3).

As you know, I switched the overall default setting for the component placement from inside to outside the frame. E.g. legends are by default placed outside the frame. (Why? To use the device windows more efficiently. In most cases, the v4 setting has larger legend item text than in v3). So that means that titles are also place outside of the frame by default. Imho, this is also nicer.

The question is how to name the tm_title elements. Now I opted for tm_title being the outside title, and tm_title_in for the inside-the-frame title. However, this is also not ideal, since I can change the default positioning of the tm_title elements in tm_options. So in case the "v3" style is enabled, it would make sense to set the position of tm_title to tm_pos_in(). Perhaps it would make sense to have both tm_title_in and tm_title_out available, as well as tm_title.

What do you think?