View source for FAQ How do I use progress monitors?

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
<tt>IProgressMonitor</tt> is an abstraction that allows for decoupling
of UI and non-UI components.

Normally you won't use the <tt>IProgressMonitor</tt> interfaces. When
you write a method that receives an <tt>IProgressMonitor</tt>, the first thing
you will do is convert it to a <tt>SubMonitor</tt> via <tt>SubMonitor.convert</tt>.

This sets the number of units of work that it will take. The work value
doesn&#146;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 use the 1-argument version of
<tt>SubMonitor.convert</tt> and then use the idiom
<tt>subMonitor.setWorkRemaining(100).split(1)</tt> to allocate
1% of the remaining space on each iteration.

After allocating the units of work, you should call <tt>SubMonitor.split</tt>
as the task progresses. The sum of the values passed to <tt>split</tt> method
must equal the total work passed to <tt>SubMonitor.convert</tt>. Each call
to <tt>SubMonitor.split</tt> returns a new <tt>SubMonitor</tt> which you can
pass into another method that receives a progress monitor. If you just ignore
the monitor returned by <tt>split</tt>, all of its progress will be reported
the next time you use its parent monitor.

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

<pre>
   SubMonitor subMonitor = SubMonitor.convert(monitor, 10);
   subMonitor.setTaskName("Performing decathlon: ");
   subMonitor.subTask("hammer throw");
   //perform the hammer throw
   doHammerThrow(subMonitor.split(1));
   //... repeat for remaining nine events
</pre>

The monitor can also be used to respond to cancellation requests.
Each call to <tt>SubMonitor.split</tt> checks if the monitor has been
cancelled and will throw <tt>OperationCanceledException</tt> if so.

[https://eclipse.org/articles/Article-Progress-Monitors/article.html This article]
offers some more useful examples.

== See Also: ==
*The [https://eclipse.org/articles/Article-Progress-Monitors/article.html Using Progress Monitors] article offers more useful examples
*[[FAQ How do I use a SubProgressMonitor?]]
*[[FAQ Why should I use the new progress service?]]

{{Template:FAQ_Tagline}}