| 1 |
lars |
1 |
In general, to generate a progress bar you will call the constructor, then call
|
|
|
2 |
the update() method in a loop.
|
|
|
3 |
You can use the reset() method to reuse one object to display another bar. Its
|
|
|
4 |
parameters are the same as the constructor.
|
|
|
5 |
|
|
|
6 |
The Constructor expects 5 to 6 arguments:
|
|
|
7 |
- The first argument is the format string used to display the progress
|
|
|
8 |
bar. It may (and should) contain placeholders that the class will
|
|
|
9 |
replace with information like the progress bar itself, the progress in
|
|
|
10 |
percent, and so on. Current placeholders are:
|
|
|
11 |
%bar% The progress bar
|
|
|
12 |
%current% The current value
|
|
|
13 |
%max% The maximum malue (the "target" value)
|
|
|
14 |
%fraction% The same as %current%/%max%
|
|
|
15 |
%percent% The status in percent
|
|
|
16 |
%elapsed% The elapsed time
|
|
|
17 |
%estimate% An estimate for the remaining time
|
|
|
18 |
More placeholders will follow. A format string like:
|
|
|
19 |
"* stuff.tar %fraction% KB [%bar%] %percent%"
|
|
|
20 |
will lead to a bar looking like this:
|
|
|
21 |
"* stuff.tar 391/900 KB [=====>---------] 43.44%"
|
|
|
22 |
- The second argument is the string that is going to fill the progress
|
|
|
23 |
bar. In the above example, the string "=>" was used. If the string you
|
|
|
24 |
pass is too short (like "=>" in this example), the leftmost character
|
|
|
25 |
is used to pad it to the needed size. If the string you pass is too long,
|
|
|
26 |
excessive characters are stripped from the left.
|
|
|
27 |
- The third argument is the string that fills the "empty" space in the
|
|
|
28 |
progress bar. In the above example, that would be "-". If the string
|
|
|
29 |
you pass is too short (like "-" in this example), the rightmost
|
|
|
30 |
character is used to pad it to the needed size. If the string you pass
|
|
|
31 |
is too short, excessive characters are stripped from the right.
|
|
|
32 |
- The fourth argument specifies the width of the display. If the options
|
|
|
33 |
are left untouched, it will tell how many characters the display should
|
|
|
34 |
use in total. If the "absolute_width" option is set to false, it tells
|
|
|
35 |
how many characters the actual bar (that replaces the %bar%
|
|
|
36 |
placeholder) should use.
|
|
|
37 |
- The fifth argument is the target number of the progress bar. For
|
|
|
38 |
example, if you wanted to display a progress bar for a download of a
|
|
|
39 |
file that is 115 KB big, you would pass 115 here.
|
|
|
40 |
- The sixth argument optional. If passed, it should contain an array of
|
|
|
41 |
options. For example, passing array('absolute_width' => false) would
|
|
|
42 |
set the absolute_width option to false. Current options are:
|
|
|
43 |
|
|
|
44 |
option | def. | meaning
|
|
|
45 |
--------------------------------------------------------------------
|
|
|
46 |
percent_precision | 2 | Number of decimal places to show when
|
|
|
47 |
| | displaying the percentage.
|
|
|
48 |
fraction_precision | 0 | Number of decimal places to show when
|
|
|
49 |
| | displaying the current or target
|
|
|
50 |
| | number.
|
|
|
51 |
percent_pad | ' ' | Character to use when padding the
|
|
|
52 |
| | percentage to a fixed size. Senseful
|
|
|
53 |
| | values are ' ' and '0', but any are
|
|
|
54 |
| | possible.
|
|
|
55 |
fraction_pad | ' ' | Character to use when padding max and
|
|
|
56 |
| | current number to a fixed size.
|
|
|
57 |
| | Senseful values are ' ' and '0', but
|
|
|
58 |
| | any are possible.
|
|
|
59 |
width_absolute | true | If the width passed as an argument
|
|
|
60 |
| | should mean the total size (true) or
|
|
|
61 |
| | the width of the bar alone.
|
|
|
62 |
ansi_terminal | false | If this option is true, a better
|
|
|
63 |
| | (faster) method for erasing the bar is
|
|
|
64 |
| | used.
|
|
|
65 |
ansi_clear | false | If the bar should be cleared everytime
|
|
|
66 |
num_datapoints | 5 | How many datapoints to use to create
|
|
|
67 |
| | the estimated remaining time
|
|
|
68 |
|
|
|
69 |
The update() method expects just one parameter, the current status (somewhere
|
|
|
70 |
between 0 and the target number passed to the constructor) and refreshes the
|
|
|
71 |
display (or starts it, if it's the first call).
|