Difference between revisions of "FAQ How do I use progress monitors?"

Revision as of 14:01, 30 May 2013

A progress monitor is a callback interface that allows a long-running task to report progress and respond to cancellation. Typically, a UI component will create a monitor instance and pass it to a low-level component that does not know or care about the UI. Thus, an IProgressMonitor is an abstraction that allows for decoupling of UI and non-UI components.

Each monitor instance has a strictly defined lifecycle. The first method that must be called is beginTask, which specifies a description of the operation and the number of units of work that it will take. This work value doesn’t need to be very precise; your goal here is to give the user a rough estimate of how long it will take. If you have no way of estimating the amount of work, you can pass a work value of IProgressMonitor.UNKNOWN, which will result in a continuously animated progress monitor that does not give any useful information to the user.

After beginTask, you should call subTask and worked periodically as the task progresses. The sum of the values passed to the worked method must equal the total work passed to beginTask. The subTask messages can be sent as often as you like, as they provide more details about what part of the task is currently executing. Again, you don’t need to be precise here. Simply give the user a rough idea of what is going on.

Finally, you must call done on the monitor. One consequence of calling done is that any unused portion of the progress bar will be filled up. If your code is part of a larger operation, failing to call done will mean that the portion of the progress bar allotted to your part of the operation will not be filled. To ensure done gets called, you should place it in a finally block at the very end of your operation.

Here is a complete example of a long-running operation reporting progress:

   try {
      monitor.beginTask("Performing decathlon: ", 10);
      monitor.subTask("hammer throw");
      //perform the hammer throw
      monitor.worked(1);
      //... repeat for remaining nine events
   } finally {
      monitor.done();
   }

The monitor can also be used to respond to cancellation requests. When the user requests cancellation, the method isCanceled will return true. Your long-running operation should check this value occasionally and abort if a cancellation has occurred. A common method of quickly aborting a long-running operation is to throw OperationCanceledException.

See Also:

• FAQ How do I use a SubProgressMonitor?
• FAQ Why should I use the new progress service?