\HeaderA{txtProgressBar}{Text Progress Bar}{txtProgressBar}
\aliasA{close.txtProgressBar}{txtProgressBar}{close.txtProgressBar}
\aliasA{getTxtProgressBar}{txtProgressBar}{getTxtProgressBar}
\aliasA{setTxtProgressBar}{txtProgressBar}{setTxtProgressBar}
\keyword{utilities}{txtProgressBar}
\begin{Description}\relax
Text progress bar in the \R{} console.
\end{Description}
\begin{Usage}
\begin{verbatim}
txtProgressBar(min = 0, max = 1, initial = 0, char = "=",
               width = NA, title, label, style = 1)

getTxtProgressBar(pb)
setTxtProgressBar(pb, value, title = NULL, label = NULL)
## S3 method for class 'txtProgressBar':
close(con, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{min, max}] (finite) numeric values for the extremes of the
progress bar.
\item[\code{initial, value}] initial or new value for the progress bar.
\item[\code{char}] the character (or character string) to form the progress bar.
\item[\code{width}] the width of the progress bar, as a multiple of the width
of \code{char}.  If \code{NA}, the default, the number of characters
is that which fits into \code{getOption("width")}.
\item[\code{style}] the \sQuote{style} of the bar -- see \sQuote{Details}.
\item[\code{pb, con}] an object of class \code{"txtProgressBar"}.
\item[\code{title, label}] ignored, for compatibility with other progress bars.
\item[\code{...}] for consistency with the generic.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{txtProgressBar} will display a progress bar on the \R{} console
via a text representation.

\code{setTxtProgessBar} will update the value.  Missing
(\code{\LinkA{NA}{NA}}) and out-of-range values of \code{value} will be
(silently) ignored.

The progress bar should be \code{close}d when finished with: this
outputs the final newline character.

\code{style = 1} and \code{style = 2} just shows a line of
\code{char}. They differ in that \code{style = 2} redraws the line
each time, which is useful if other code might be writing to the \R{}
console.  \code{style = 3} marks the end of the range by \code{|} and
gives a percentage to the right of the bar.
\end{Details}
\begin{Value}
For \code{txtProgressBar} an object of class \code{"txtProgressBar"}.

For \code{getTxtProgressBar} and \code{setTxtProgressBar}, a
length-one numeric vector giving the previous value (invisibly for
\code{setTxtProgressBar}).
\end{Value}
\begin{Note}\relax
Using \code{style} 2 or 3 or reducing the value with \code{style = 1}
uses \samp{\r} to return to the left margin -- the interpretation of
carriage return is up to the terminal or console in which \R{} is running.
\end{Note}
\begin{SeeAlso}\relax
\code{\LinkA{tkProgressBar}{tkProgressBar}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode} # slow
testit <- function(x = sort(runif(20)), ...)
{
    pb <- txtProgressBar(...)
    for(i in c(0, x, 1)) {Sys.sleep(0.5); setTxtProgressBar(pb, i)}
    Sys.sleep(1)
    close(pb)
}
testit()
testit(runif(10))
testit(style=3)
\end{ExampleCode}
\end{Examples}

