.. meta::
    :description: Infrastructure Progress Bar

.. _progressBars:

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:

#. instantiating a :class:`ORSModel.ors.Progress` object;
#. performing the configuration setup;
#. starting the progress (to make it appear);
#. updating the progress value (if required);
#. 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 :func:`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

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
:meth:`ORSModel.ors.Progress.startWorkingProgressWithCaption` or
:meth:`ORSModel.ors.Progress.startWorkingProgressWithID`.

To show an estimation of the remaining time in the progress bar window, start the progress with the method
:meth:`ORSModel.ors.Progress.startProgressWithCaption` or
:meth:`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
:meth:`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)

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)

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

Demos
-----

.. _sourcecodeexample_plugin_DemoProgress_fabbb140f16b11e7bc70448a5b5d70c0:

Source code example:

#. Download the :download:`compressed file </Documentation/Zipped/DemoProgress_fabbb140f16b11e7bc70448a5b5d70c0.zip>`;
#. Extract these files into a :ref:`plugin extension folder <filesLocationPluginExtension>`;
#. Start the application;
#. Open the top level menu *Demos* to see the menu item named *Demo: progress bar*;
#. By clicking on the menu item, an instance of the plugin will be created
   and his mainform will be displayed;
#. Set the first (lower) and last (higher) value to test as prime numbers;
#. To show the estimated remaining time in the progress window, mark the check box *Show estimated remaining time*;
#. To have a *Cancel* button in the progress window, mark the check box *Progress bar is cancellable*;
#. Press the *Start evaluation of prime numbers* button to start evaluating what are the prime numbers between
   the lower and higher specified values;
#. 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.