ProgressBar Element Documentation
- NAME
- SYNOPSIS
- DESCRIPTION
- EXAMPLES
- NOTES
- ELEMENT HANDLERS
- SEE ALSO
- COMMENTS

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

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)

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.