7. Progress Bars

Progress bars are used to help the user determine how much time a possibly long computation will take and to cancel the computation before it is completed.

Using a progress bar is done by:

1. instantiating a ORSModel.ors.Progress object;
2. performing the configuration setup;
3. starting the progress (to make it appear);
4. updating the progress value (if required);
5. closing the progress.

Since the progress bar is a visual element and would have to be refreshed with the UI, it is important to perform the extensive computation in another thread, while the main thread (which is the thread of the UI) remain callable. To do so, we use the ORSServiceClass.decorators.decorators.run_in_background_waiting_until_finished() decorator on the function to be run in the other thread. While in the decorated method, the UI is disabled for any user events, except for interacting with the progress window (to allow using the cancellation button, if present).

The basic syntax for using a progress bar is:

def callForProgress(self):
    # Instantiation of the progress object
    progress = Progress()

    # Calling a method run in another thread
    self._methodWithLongComputingTime(progress)

    # Closing and deletion of the progress object
    progress.deleteObject()

@run_in_background_waiting_until_finished
def _methodWithLongComputingTime(self, progress):
    # Configuration and start of the progress
    progressWindowTitle = 'A title'
    isCancellable = False
    progress.startWorkingProgressWithCaption(progressWindowTitle, isCancellable)

    # Performing the computation
    pass

7.1. Estimated remaining time

To use a progress bar that doesn’t show the estimated remaining time (for simplicity or because there is no way to determine the computation effort), start the progress with the method ORSModel.ors.Progress.startWorkingProgressWithCaption() or ORSModel.ors.Progress.startWorkingProgressWithID().

To show an estimation of the remaining time in the progress bar window, start the progress with the method ORSModel.ors.Progress.startProgressWithCaption() or ORSModel.ors.Progress.startProgressWithID(). An argument of these methods is the range of the progression. During the computation, the progression value has to be specified with the method ORSModel.ors.Progress.updateProgress() with a value between 0 and the given range value. When the UI is updated, the estimated remaining time is computed and displayed.

Example:

progressWindowTitle = 'A title'
progressRange = 50  # Range of the progression
isCancellable = False
progress.startProgressWithCaption(progressWindowTitle, progressRange, isCancellable)

for progressIndex in range(1, progressRange+1):
    # Performing the computation
    pass

    # Updating the progress value
    progress.updateProgress(progressIndex)

7.2. Cancelling a progress

To allow a computation to be cancelled (interrupted), start the progress using the argument for the cancellation. A button will be shown next to the progress bar. In the code, it is possible to check for this cancellation state to determine if the computation should be interrupted:

progressWindowTitle = 'A title'
progressRange = 50  # Range of the progression
isCancellable = True
progress.startProgressWithCaption(progressWindowTitle, progressRange, isCancellable)

for progressIndex in range(1, progressRange+1):
    # Performing the computation
    pass

    # Testing for cancellation
    if progress.getIsCancelled():
        # The progress has been cancelled.
        # Exit.
        break

    # Updating the progress value
    progress.updateProgress(progressIndex)

7.3. Using IDs

The title of the progress bar window can be obtained by either specifying the title as argument (for the methods ORSModel.ors.Progress.startWorkingProgressWithCaption() and ORSModel.ors.Progress.startProgressWithCaption()) or by using an ID (for the methods ORSModel.ors.Progress.startWorkingProgressWithID() and ORSModel.ors.Progress.startProgressWithID()). See Progress bar IDs for the available progress IDs.

7.4. Demos

Source code example:

1. Download the compressed file;
2. Extract these files into a plugin extension folder;
3. Start the application;
4. Open the top level menu Demos to see the menu item named Demo: progress bar;
5. By clicking on the menu item, an instance of the plugin will be created and his mainform will be displayed;
6. Set the first (lower) and last (higher) value to test as prime numbers;
7. To show the estimated remaining time in the progress window, mark the check box Show estimated remaining time;
8. To have a Cancel button in the progress window, mark the check box Progress bar is cancellable;
9. Press the Start evaluation of prime numbers button to start evaluating what are the prime numbers between the lower and higher specified values;
10. When the evaluation is complete, the prime numbers in the tested range are written in the text box. If the evaluation is interrupted by hitting the Cancel button, the prime numbers written are those found in the range of tested numbers.