1
#' Set tmap mode to static plotting or interactive viewing
2
#' 
3
#' Set tmap mode to static plotting or interactive viewing. The global option \code{tmap.mode} determines the whether thematic maps are plot in the graphics device, or shown as an interactive leaflet map (see also \code{\link{tmap_options}}. The function \code{tmap_mode} is a wrapper to set this global option. The convenient function \code{ttm} is a toggle switch between the two modes. Tip 1: use \code{tmap_mode} in scripts and \code{ttm} in the console. Tip 2: use \code{ttm} in combination with \code{\link{tmap_last}} to redraw the last map in the other mode.
4
#' 
5
#' @param mode one of
6
#' \describe{
7
#'    	\item{\code{"plot"}}{Thematic maps are shown in the graphics device. This is the default mode, and supports all tmap's features, such as small multiples (see \code{\link{tm_facets}}) and extensive layout settings (see \code{\link{tm_layout}}). It is recommended for saving static maps (see \code{\link{tmap_save}}).} 
8
#'    	\item{\code{"view"}}{Thematic maps are viewed interactively in the web browser or RStudio's Viewer pane. Maps are fully interactive with tiles from OpenStreetMap or other map providers (see \code{\link{tm_tiles}}). See also \code{\link{tm_view}} for options related to the \code{"view"} mode. This mode generates a \code{\link[leaflet:leaflet]{leaflet}} widget, which can also be directly obtained with \code{\link{tmap_leaflet}}. With RMarkdown, it is possible to publish it to an HTML page. 
9
#'    	There are a couple of constraints in comparison to \code{"plot"}:
10
#'    	\itemize{
11
#'    	\item The map is always projected according to the Web Mercator projection. Although this projection is the de facto standard for interactive web-based mapping, it lacks the equal-area property, which is important for many thematic maps, especially choropleths (see examples from \code{\link{tm_shape}}).
12
#'    	\item Small multiples are not supported
13
#'    	\item The legend cannot be made for aesthetics regarding size, which are symbol size and line width.
14
#'    	\item Text labels are not supported (yet)
15
#'    	\item The layout options set with \code{\link{tm_layout}}) regarding map format are not used. However, the styling options still apply.}
16
#'    	}}
17
#' @return the mode before changing
18
#' @example ./examples/tmap_mode.R
19
#' @seealso \href{../doc/tmap-getstarted.html}{\code{vignette("tmap-getstarted")}}, \code{\link{tmap_last}} to show the last map, \code{\link{tm_view}} for viewing options, and \code{\link{tmap_leaflet}} for obtaining a leaflet widget, and \code{\link{tmap_options}} for tmap options.
20
#' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \href{https://doi.org/10.18637/jss.v084.i06}{DOI}
21
#' @export
22
tmap_mode <- function(mode=c("plot", "view")) {
23 2
	current.mode <- getOption("tmap.mode")
24 2
	show.messages <- get(".tmapOptions", envir = .TMAP_CACHE)$show.messages
25
	
26 2
	if (is.null(match.call(expand.dots = TRUE)[-1])) {
27 0
		message("current tmap mode is \"", current.mode, "\"")
28 2
	} else {
29 2
		mode <- match.arg(mode)
30 2
		options(tmap.mode=mode)
31 2
		if (show.messages) {
32 2
			if (mode=="plot") {
33 2
				message("tmap mode set to plotting")
34 2
			} else {
35 2
				message("tmap mode set to interactive viewing")
36 2
			}
37 2
		}
38 2
	}
39 2
	invisible(current.mode)
40
}	
41

42
#' @rdname tmap_mode
43
#' @export
44
ttm <- function() {
45 2
	current.mode <- getOption("tmap.mode")
46 2
	tmap_mode(ifelse(current.mode=="plot", "view", "plot"))
47 2
	invisible(current.mode)
48
}
49

50
check_mode <- function(mode) {
51 0
	if (!mode %in% (c("plot", "view"))) stop("incorrect mode", call. = FALSE)
52
}
53

54

55
check_unit <- function(unit) {
56 0
	if (!unit %in% c("metric", "imperial", "km", "m", "mi", "miles", "ft", "feet")) stop("incorrect unit", call. = FALSE)
57
}

Read our documentation on viewing source code .

Loading