2.8.1 ProgressBar Objects

Python PEP

previous page next page

2.8.1 ProgressBar Objects

ProgressBar objects provide support for modeless progress-bar dialogs. Both determinate (thermometer style) and indeterminate (barber-pole style) progress bars are supported. The bar will be determinate if its maximum value is greater than zero; otherwise it will be indeterminate. Changed in version 2.2: Support for indeterminate-style progress bars was added.

The dialog is displayed immediately after creation. If the dialog's ``Cancel'' button is pressed, or if Cmd-. or ESC is typed, the dialog window is hidden and KeyboardInterrupt is raised (but note that this response does not occur until the progress bar is next updated, typically via a call to inc() or set()). Otherwise, the bar remains visible until the ProgressBar object is discarded.

ProgressBar objects possess the following attributes and methods:

curval: The current value (of type integer or long integer) of the progress bar. The normal access methods coerce curval between 0 and maxval. This attribute should not be altered directly.

maxval: The maximum value (of type integer or long integer) of the progress bar; the progress bar (thermometer style) is full when curval equals maxval. If maxval is 0, the bar will be indeterminate (barber-pole). This attribute should not be altered directly.

title( [newstr]): Sets the text in the title bar of the progress dialog to newstr.

label( [newstr]): Sets the text in the progress box of the progress dialog to newstr.

set( value[, max]): Sets the progress bar's curval to value, and also maxval to max if the latter is provided. value is first coerced between 0 and maxval. The thermometer bar is updated to reflect the changes, including a change from indeterminate to determinate or vice versa.

inc( [n]): Increments the progress bar's curval by n, or by 1 if n is not provided. (Note that n may be negative, in which case the effect is a decrement.) The progress bar is updated to reflect the change. If the bar is indeterminate, this causes one ``spin'' of the barber pole. The resulting curval is coerced between 0 and maxval if incrementing causes it to fall outside this range.

See About this document... for information on suggesting changes.

previous page start next page