diff --git a/NAMESPACE b/NAMESPACE index 267cde5334..9f2c512f1e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -469,6 +469,7 @@ export(theme_grey) export(theme_light) export(theme_linedraw) export(theme_minimal) +export(theme_replace) export(theme_set) export(theme_update) export(theme_void) diff --git a/NEWS.md b/NEWS.md index 4883f67e74..288a40291f 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,9 @@ # ggplot2 2.0.0.9000 +* `theme_update()` now uses the `+` operator instead of `%+replace%`, so that + unspecified values will no longer be `NULL`ed out. `theme_replace()` + preserves the old behaviour if desired (@oneillkza, #1519). + * `layer()` now accepts a function as the data argument. The function will be applied to the data passed to the `ggplot()` function and must return a data.frame (#1527). diff --git a/R/theme.r b/R/theme.r index d8be07abc5..32f79a52a4 100644 --- a/R/theme.r +++ b/R/theme.r @@ -1,7 +1,13 @@ #' Get, set and update themes. #' -#' Use \code{theme_update} to modify a small number of elements of the current -#' theme or use \code{theme_set} to completely override it. +#' Use \code{theme_get} to get the current theme, and \code{theme_set} to +#' completely override it. \code{theme_update} and \code{theme_replace} are +#' shorthands for changing individual elements in the current theme. +#' \code{theme_update} uses the \code{+} operator, so that any unspecified +#' values in the theme element will default to the values they are set in the +#' theme. \code{theme_replace} will completely replace the element, so any +#' unspecified values will overwrite the current value in the theme with \code{NULL}s. +#' #' #' @param ... named list of theme settings #' @seealso \code{\link{\%+replace\%}} and \code{\link{+.gg}} @@ -15,19 +21,37 @@ #' theme_set(old) #' p #' +#' #theme_replace NULLs out the fill attribute of panel.background, +#' #resulting in a white background: +#' theme_get()$panel.background +#' old <- theme_replace(panel.background = element_rect(colour = "pink")) +#' theme_get()$panel.background +#' p +#' theme_set(old) +#' +#' #theme_update only changes the colour attribute, leaving the others intact: #' old <- theme_update(panel.background = element_rect(colour = "pink")) +#' theme_get()$panel.background #' p #' theme_set(old) +#' #' theme_get() #' +#' #' ggplot(mtcars, aes(mpg, wt)) + #' geom_point(aes(color = mpg)) + #' theme(legend.position = c(0.95, 0.95), #' legend.justification = c(1, 1)) #' last_plot() + #' theme(legend.background = element_rect(fill = "white", colour = "white", size = 3)) +#' theme_update <- function(...) { - # Make a call to theme, then add to theme + theme_set(theme_get() + theme(...)) +} + +#' @rdname theme_update +#' @export +theme_replace <- function(...) { theme_set(theme_get() %+replace% theme(...)) } diff --git a/man/stat_summary.Rd b/man/stat_summary.Rd index 837ff9a449..856fc490f9 100644 --- a/man/stat_summary.Rd +++ b/man/stat_summary.Rd @@ -66,7 +66,7 @@ the default plot specification, e.g. \code{\link{borders}}.} \description{ \code{stat_summary} operates on unique \code{x}; \code{stat_summary_bin} operators on binned \code{x}. They are more flexible versions of -\code{\link{stat_bin}}: instead of just counting, the can compute any +\code{\link{stat_bin}}: instead of just counting, they can compute any aggregate. } \section{Aesthetics}{ diff --git a/man/theme_update.Rd b/man/theme_update.Rd index 6cabafe121..ec90647127 100644 --- a/man/theme_update.Rd +++ b/man/theme_update.Rd @@ -2,12 +2,15 @@ % Please edit documentation in R/theme.r \name{theme_update} \alias{theme_get} +\alias{theme_replace} \alias{theme_set} \alias{theme_update} \title{Get, set and update themes.} \usage{ theme_update(...) +theme_replace(...) + theme_get() theme_set(new) @@ -18,8 +21,13 @@ theme_set(new) \item{new}{new theme (a list of theme elements)} } \description{ -Use \code{theme_update} to modify a small number of elements of the current -theme or use \code{theme_set} to completely override it. +Use \code{theme_get} to get the current theme, and \code{theme_set} to +completely override it. \code{theme_update} and \code{theme_replace} are +shorthands for changing individual elements in the current theme. +\code{theme_update} uses the \code{+} operator, so that any unspecified +values in the theme element will default to the values they are set in the +theme. \code{theme_replace} will completely replace the element, so any +unspecified values will overwrite the current value in the theme with \code{NULL}s. } \examples{ p <- ggplot(mtcars, aes(mpg, wt)) + @@ -30,17 +38,30 @@ p theme_set(old) p +#theme_replace NULLs out the fill attribute of panel.background, +#resulting in a white background: +theme_get()$panel.background +old <- theme_replace(panel.background = element_rect(colour = "pink")) +theme_get()$panel.background +p +theme_set(old) + +#theme_update only changes the colour attribute, leaving the others intact: old <- theme_update(panel.background = element_rect(colour = "pink")) +theme_get()$panel.background p theme_set(old) + theme_get() + ggplot(mtcars, aes(mpg, wt)) + geom_point(aes(color = mpg)) + theme(legend.position = c(0.95, 0.95), legend.justification = c(1, 1)) last_plot() + theme(legend.background = element_rect(fill = "white", colour = "white", size = 3)) + } \seealso{ \code{\link{\%+replace\%}} and \code{\link{+.gg}}