1% File src/library/utils/man/winProgressBar.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 2008-2018 R Core Team
4% Distributed under GPL 2 or later
5
6\name{winProgressBar}
7\alias{winProgressBar}
8\alias{getWinProgressBar}
9\alias{setWinProgressBar}
10\alias{close.winProgressBar}
11\title{Progress Bars under MS Windows}
12\description{
13  Put up a Windows progress bar widget, update and access it.
14}
15\usage{
16winProgressBar(title = "R progress bar", label = "",
17               min = 0, max = 1, initial = 0, width = 300)
18
19getWinProgressBar(pb)
20setWinProgressBar(pb, value, title = NULL, label = NULL)
21\method{close}{winProgressBar}(con, \dots)
22}
23\arguments{
24  \item{title, label}{character strings, giving the window title and the
25    label on the dialog box respectively.}
26  \item{min, max}{(finite) numeric values for the extremes of the
27    progress bar.}
28  \item{initial, value}{initial or new value for the progress bar.}
29  \item{width}{the width of the progress bar in pixels: the dialog box
30    will be 40 pixels wider (plus frame).}
31  \item{pb, con}{an object of class \code{"winProgressBar"}.}
32  \item{\dots}{for consistency with the generic.}
33}
34\details{
35  \code{winProgressBar} will display a progress bar centred on the
36  screen.  Space will be allocated for the label only if it is non-empty.
37
38  \code{setWinProgessBar} will update the value and for non-\code{NULL}
39  values, the title and label (provided there was one when the widget
40  was created).  Missing (\code{\link{NA}}) and out-of-range values of
41  \code{value} will be (silently) ignored.
42
43  The progress bar should be \code{close}d when finished with, but it
44  will be garbage-collected once no \R object refers to it.
45}
46\value{
47  For \code{winProgressBar} an object of class \code{"winProgressBar"}.
48
49  For \code{getWinProgressBar} and \code{setWinProgressBar}, a
50  length-one numeric vector giving the previous value (invisibly for
51  \code{setWinProgressBar}).
52}
53\note{
54  These functions are only available on Windows.% incl RStudio, not yet in ESS
55}
56\seealso{
57  On all platforms,
58  \code{\link{txtProgressBar}}, \code{\link{tkProgressBar}}
59}
60\examples{\donttest{% popups are irritating
61pb <- winProgressBar("test progress bar", "Some information in \%",
62                     0, 100, 50)
63Sys.sleep(0.5)
64u <- c(0, sort(runif(20, 0, 100)), 100)
65for(i in u) {
66    Sys.sleep(0.1)
67    info <- sprintf("\%d\%\% done", round(i))
68    setWinProgressBar(pb, i, sprintf("test (\%s)", info), info)
69}
70Sys.sleep(5)
71close(pb)
72}}
73\keyword{utilities}
74