Reporting progress (functional API) — withProgress
R/progress.R
Description
Reports progress to the user during long-running operations.
withProgress(
expr,
min = 0,
max = 1,
value = min + (max - min) * 0.1,
message = NULL,
detail = NULL,
style = getShinyOption("progress.style", default = "notification"),
session = getDefaultReactiveDomain(),
env = parent.frame(),
quoted = FALSE
)
setProgress(
value = NULL,
message = NULL,
detail = NULL,
session = getDefaultReactiveDomain()
)
incProgress(
amount = 0.1,
message = NULL,
detail = NULL,
session = getDefaultReactiveDomain()
)
Arguments
- expr
The work to be done. This expression should contain calls to
setProgress()
orincProgress()
.- min
The value that represents the starting point of the progress bar. Must be less tham
max
. Default is 0.- max
The value that represents the end of the progress bar. Must be greater than
min
. Default is 1.- value
Single-element numeric vector; the value at which to set the progress bar, relative to
min
andmax
.- message
A single-element character vector; the message to be displayed to the user, or
NULL
to hide the current message (if any).- detail
A single-element character vector; the detail message to be displayed to the user, or
NULL
to hide the current detail message (if any). The detail message will be shown with a de-emphasized appearance relative tomessage
.- style
Progress display style. If
"notification"
(the default), the progress indicator will show using Shiny's notification API. If"old"
, use the same HTML and CSS used in Shiny 0.13.2 and below (this is for backward-compatibility).- session
The Shiny session object, as provided by
shinyServer
to the server function. The default is to automatically find the session by using the current reactive domain.- env
The environment in which
expr
should be evaluated.- quoted
Whether
expr
is a quoted expression (this is not common).- amount
For
incProgress
, the amount to increment the status bar. Default is 0.1.
Value
The result of expr
.
Details
This package exposes two distinct programming APIs for working with progress.
Using withProgress
with incProgress
or setProgress
provide a simple function-based interface, while the Progress()
reference class provides an object-oriented API.
Use withProgress
to wrap the scope of your work; doing so will cause a
new progress panel to be created, and it will be displayed the first time
incProgress
or setProgress
are called. When withProgress
exits, the corresponding progress panel will be removed.
The incProgress
function increments the status bar by a specified
amount, whereas the setProgress
function sets it to a specific value,
and can also set the text displayed.
Generally, withProgress
/incProgress
/setProgress
should
be sufficient; the exception is if the work to be done is asynchronous (this
is not common) or otherwise cannot be encapsulated by a single scope. In that
case, you can use the Progress
reference class.
As of version 0.14, the progress indicators use Shiny's new notification API.
If you want to use the old styling (for example, you may have used customized
CSS), you can use style="old"
each time you call
withProgress()
. If you don't want to set the style each time
withProgress
is called, you can instead call
shinyOptions(progress.style="old")
just once, inside the server
function.
See also
Examples
## Only run examples in interactive R sessions
if (interactive()) {
options(device.ask.default = FALSE)
ui <- fluidPage(
plotOutput("plot")
)
server <- function(input, output) {
output$plot <- renderPlot({
withProgress(message = 'Calculation in progress',
detail = 'This may take a while...', value = 0, {
for (i in 1:15) {
incProgress(1/15)
Sys.sleep(0.25)
}
})
plot(cars)
})
}
shinyApp(ui, server)
}