<box begindoc>**This is automatically generated documentation.**  Edit after the "[[#COMMENTS|COMMENTS]]" heading; changes to the main body will be lost.</box>

====== ProgressBar Element Documentation ======

===== NAME =====

**ProgressBar** -- Click element;
prints a progress bar to standard error

===== SYNOPSIS =====

ProgressBar(POSHANDLER [, SIZEHANDLER, //KEYWORDS//])

**Ports**: none\\ 
**Drivers**: userlevel\\ 
**Package**: userlevel (core)\\ 

===== DESCRIPTION =====

Reads progress information from handlers, and displays an ASCII-art progress
bar on standard error, indicating how much progress has been made and how much
remains to go.
POSHANDLER and SIZEHANDLER are read handlers. Each of them should return a
nonnegative real number. POSHANDLER is checked each time the progress bar
displays; SIZEHANDLER is checked just once, the first time the progress bar
comes up. Intuitively, POSHANDLER represents the "position"; the process is
complete when its value equals the "size" returned by SIZEHANDLER. You may
give multiple position and/or size handlers, as a space-separated list; their
values are added together.
Keyword arguments are:


 ? **FIXED_SIZE**
 ! Nonnegative real number. Used as the size when SIZEHANDLER is not supplied.
Default is no fixed size.

 ? **BANNER**
 ! String. Print this string before the progress bar. For example, this might be
a section of some filename. Default is empty.

 ? **UPDATE**
 ! Time in seconds (millisecond precision). The progress bar updates itself with
this frequency. Default is 1/4 second.

 ? **ACTIVE**
 ! Boolean. The progress bar will not initially display itself if this is false.
Default is true.

 ? **DELAY**
 ! Time in seconds (millisecond precision). Don't print a progress bar until at
least DELAY seconds have passed. Use this to avoid trivial progress bars (that
is, progress bars that immediately go to 100%). Default is no delay.

 ? **CHECK_STDOUT**
 ! Boolean. If true, and the standard output is connected to a terminal, then do
not print a progress bar. Default is false.
Only available in user-level processes.

===== EXAMPLES =====

This ProgressBar shows how far into the file [[FromDump]] has gotten:
    fd :: FromDump(~/largedump.gz) -> ...
    ProgressBar(fd.filepos, fd.filesize);
Here are some example progress bars. The first form occurs when the file size
is known; the second, when it is not known.
     74% |**************     | 23315KB    00:01 ETA
    
    |           ***          |  5184KB    --:-- ETA


===== NOTES =====

Code based on the progress bar in the OpenSSH project's **scp** program, whose
authors are listed as Timo Rinne, Tatu Ylonen, Theo de Raadt, and Aaron
Campbell.


===== ELEMENT HANDLERS =====


 ? **mark_stopped (write-only)**
 ! When written, the progress bar changes to indicate that the transfer has
stopped, possibly prematurely.

 ? **mark_done (write-only)**
 ! When written, the progress bar changes to indicate that the transfer has
successfully completed.

 ? **pos (read-only)**
 ! Returns the progress bar's current position.

 ? **size (read/write)**
 ! Returns or sets the progress bar's size value, which is used to compute how
close the process is to completion.

 ? **active (read/write)**
 ! Returns or sets the ACTIVE setting, a Boolean value. An inactive progress bar
will not redraw itself.

 ? **banner (read/write)**
 ! Returns or sets the BANNER string.

 ? **poshandler (read/write)**
 ! Returns or sets the read handlers used to read the position, as a
space-separated list.

 ? **sizehandler (read/write)**
 ! Returns or sets the read handlers used to read the size, as a space-separated
list.

 ? **reset (write-only)**
 ! When written, resets the progress bar to its initial state: the size is read
again, for example. Also sets ACTIVE to true.


===== SEE ALSO =====

[[FromDump]]


Generated by 'click-elem2man' from '../elements/userlevel/progressbar.hh' on 24/May/2007.


===== COMMENTS =====