This is automatically generated documentation. Edit after the "COMMENTS" heading; changes to the main body will be lost.

ProgressBar Element Documentation


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



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


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:

Nonnegative real number. Used as the size when SIZEHANDLER is not supplied. Default is no fixed size.
String. Print this string before the progress bar. For example, this might be a section of some filename. Default is empty.
Time in seconds (millisecond precision). The progress bar updates itself with this frequency. Default is 1/4 second.
Boolean. The progress bar will not initially display itself if this is false. Default is true.
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.
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.


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


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.


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.



Generated by 'click-elem2man' from '../elements/userlevel/progressbar.hh' on 7/Mar/2009.


elements/progressbar.txt · Last modified: 2009/03/07 17:24 (external edit)
Recent changes RSS feed Driven by DokuWiki