Jump to: navigation, search

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

m
 
(2 intermediate revisions by 2 users not shown)
Line 6: Line 6:
 
of UI and non-UI components.
 
of UI and non-UI components.
  
Each monitor instance has a strictly defined lifecycle. The first
+
Normally you won't use the <tt>IProgressMonitor</tt> interfaces. When
method that must be called is <tt>beginTask</tt>, which
+
you write a method that receives an <tt>IProgressMonitor</tt>, the first thing
specifies a description of the operation and the number of units
+
you will do is convert it to a <tt>SubMonitor</tt> via <tt>SubMonitor.convert</tt>.
of work that it will take.  This 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 pass a work value of
+
<tt>IProgressMonitor.UNKNOWN</tt>, which will result in a
+
continuously animated progress monitor that does not give any
+
useful information to the user.
+
  
After <tt>beginTask</tt>, you should call <tt>subTask</tt> and
+
This sets the number of units of work that it will take. The work value
<tt>worked</tt> periodically as the task progresses. The sum
+
doesn&#146;t need to be very precise; your goal here is to give the user a
of the values passed to the <tt>worked</tt> method must equal
+
rough estimate of how long it will take. If you have no way
the total work passed to <tt>beginTask</tt>. The <tt>subTask</tt>
+
of estimating the amount of work, you can use the 1-argument version of
messages can be sent as often as you like, as they provide
+
<tt>SubMonitor.convert</tt> and then use the idiom
more details about what part of the task is currently executing.
+
<tt>subMonitor.setWorkRemaining(100).split(1)</tt> to allocate
Again, you don&#146;t need to be precise here.  Simply give the user a
+
1% of the remaining space on each iteration.
rough idea of what is going on.
+
  
Finally, you must call <tt>done</tt> on the monitor. One consequence
+
After allocating the units of work, you should call <tt>SubMonitor.split</tt>
of calling <tt>done</tt> is that any unused portion of the progress
+
as the task progresses. The sum of the values passed to <tt>split</tt> method
bar will be filled up.  If your code is part of a larger operation,
+
must equal the total work passed to <tt>SubMonitor.convert</tt>. Each call
failing to call done will mean that the portion of the progress bar
+
to <tt>SubMonitor.split</tt> returns a new <tt>SubMonitor</tt> which you can
allotted to your part of the operation will not be filled.
+
pass into another method that receives a progress monitor. If you just ignore
To ensure <tt>done</tt> gets called, you
+
the monitor returned by <tt>split</tt>, all of its progress will be reported
should place it in a <tt>finally</tt> block at the very end of your operation.  
+
the next time you use its parent monitor.
  
 
Here is a complete example of a long-running operation reporting progress:
 
Here is a complete example of a long-running operation reporting progress:
  
 
<pre>
 
<pre>
   try {
+
   SubMonitor subMonitor = SubMonitor.convert(monitor, 10);
      monitor.beginTask("Performing decathlon: ", 10);
+
  subMonitor.setTaskName("Performing decathlon: ");
      monitor.subTask("hammer throw");
+
  subMonitor.subTask("hammer throw");
      //perform the hammer throw
+
  //perform the hammer throw
      monitor.worked(1);
+
  doHammerThrow(subMonitor.split(1));
      //... repeat for remaining nine events
+
  //... repeat for remaining nine events
  } finally {
+
      monitor.done();
+
  }
+
 
</pre>
 
</pre>
  
 
The monitor can also be used to respond to cancellation requests.
 
The monitor can also be used to respond to cancellation requests.
When the user requests cancellation, the method <tt>isCanceled</tt>
+
Each call to <tt>SubMonitor.split</tt> checks if the monitor has been
will return <tt>true</tt>.  Your long-running operation should check
+
cancelled and will throw <tt>OperationCanceledException</tt> if so.
this value occasionally and abort if a cancellation has occurred. A
+
 
common method of quickly aborting a long-running operation is
+
[https://eclipse.org/articles/Article-Progress-Monitors/article.html This article]
to throw <tt>OperationCanceledException</tt>.
+
offers some
  
 
== See Also: ==
 
== 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 How do I use a SubProgressMonitor?]]
 
*[[FAQ Why should I use the new progress service?]]
 
*[[FAQ Why should I use the new progress service?]]
  
<hr><font size=-2>This FAQ was originally published in [http://www.eclipsefaq.org Official Eclipse 3.0 FAQs]. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License v1.0].</font>
+
{{Template:FAQ_Tagline}}

Latest revision as of 12:20, 22 April 2016

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.

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

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 SubMonitor.convert and then use the idiom subMonitor.setWorkRemaining(100).split(1) to allocate 1% of the remaining space on each iteration.

After allocating the units of work, you should call SubMonitor.split as the task progresses. The sum of the values passed to split method must equal the total work passed to SubMonitor.convert. Each call to SubMonitor.split returns a new SubMonitor which you can pass into another method that receives a progress monitor. If you just ignore the monitor returned by split, 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:

   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

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

This article offers some

See Also:


This FAQ was originally published in Official Eclipse 3.0 FAQs. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the Eclipse Public License v1.0.