1% File src/library/utils/man/txtProgressBar.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 2008-11, 18 R Core Team
4% Distributed under GPL 2 or later
5
6\name{txtProgressBar}
7\alias{txtProgressBar}
8\alias{getTxtProgressBar}
9\alias{setTxtProgressBar}
10\alias{close.txtProgressBar}
11\title{Text Progress Bar}
12\description{
13  Text progress bar in the \R console.
14}
15\usage{
16txtProgressBar(min = 0, max = 1, initial = 0, char = "=",
17               width = NA, title, label, style = 1, file = "")
18
19getTxtProgressBar(pb)
20setTxtProgressBar(pb, value, title = NULL, label = NULL)
21\method{close}{txtProgressBar}(con, \dots)
22}
23\arguments{
24  \item{min, max}{(finite) numeric values for the extremes of the
25    progress bar. Must have \code{min < max}.}
26  \item{initial, value}{initial or new value for the progress bar.  See
27    \sQuote{Details} for what happens with invalid values.}
28  \item{char}{the character (or character string) to form the progress bar.}
29  \item{width}{the width of the progress bar, as a multiple of the width
30    of \code{char}.  If \code{NA}, the default, the number of characters
31    is that which fits into \code{getOption("width")}.}
32  \item{style}{the \sQuote{style} of the bar -- see \sQuote{Details}.}
33  \item{file}{an open connection object or \code{""} which indicates
34    the console: \code{\link{stderr}()} might be useful here.}
35  \item{pb, con}{an object of class \code{"txtProgressBar"}.}
36  \item{title, label}{ignored, for compatibility with other progress bars.}
37  \item{\dots}{for consistency with the generic.}
38}
39\details{
40  \code{txtProgressBar} will display a progress bar on the \R console
41  (or a connection) via a text representation.
42
43  \code{setTxtProgessBar} will update the value.  Missing
44  (\code{\link{NA}}) and out-of-range values of \code{value} will be
45  (silently) ignored.  (Such values of \code{initial} cause the progress
46  bar not to be displayed until a valid value is set.)
47
48  The progress bar should be \code{close}d when finished with: this
49  outputs the final newline character.
50
51  \code{style = 1} and \code{style = 2} just shows a line of
52  \code{char}. They differ in that \code{style = 2} redraws the line
53  each time, which is useful if other code might be writing to the \R
54  console.  \code{style = 3} marks the end of the range by \code{|} and
55  gives a percentage to the right of the bar.
56}
57\value{
58  For \code{txtProgressBar} an object of class \code{"txtProgressBar"}.
59
60  For \code{getTxtProgressBar} and \code{setTxtProgressBar}, a
61  length-one numeric vector giving the previous value (invisibly for
62  \code{setTxtProgressBar}).
63}
64\note{
65  Using \code{style} 2 or 3 or reducing the value with \code{style = 1}
66  uses \samp{\r} to return to the left margin -- the interpretation of
67  carriage return is up to the terminal or console in which \R is
68  running, and this is liable to produce ugly output on a connection
69  other than a terminal, including when \code{stdout()} is
70  redirected to a file.
71}
72\seealso{
73  \code{\link{winProgressBar}} (Windows only),
74  \code{\link{tkProgressBar}} (Unix-alike platforms).
75}
76\examples{\donttest{ # slow
77testit <- function(x = sort(runif(20)), ...)
78{
79    pb <- txtProgressBar(...)
80    for(i in c(0, x, 1)) {Sys.sleep(0.5); setTxtProgressBar(pb, i)}
81    Sys.sleep(1)
82    close(pb)
83}
84testit()
85testit(runif(10))
86testit(style = 3)
87}}
88\keyword{utilities}
89