Skip to main content
Jump to: navigation, search

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

 
 
(4 intermediate revisions by 3 users not shown)
Line 6: Line 6:
 
of UI and non-UI components.
 
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.
  
Each monitor instance has a strictly defined lifecycle.  The first
+
Here is a complete example of a long-running operation reporting progress:
method that must be called is <tt>beginTask</tt>, which
+
specifies a description of the operation and the number of units
+
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
 
<tt>worked</tt> periodically as the task progresses.  The sum
 
of the values passed to the <tt>worked</tt> method must equal
 
the total work passed to <tt>beginTask</tt>.  The <tt>subTask</tt>
 
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&#146;t need to be precise here.  Simply give the user a
 
rough idea of what is going on.
 
 
 
 
 
Finally, you must call <tt>done</tt> on the monitor.  One consequence
 
of calling <tt>done</tt> 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 <tt>done</tt> gets called, you
 
should place it in a <tt>finally</tt> block at the very end of your operation.
 
 
 
 
 
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
+
to throw <tt>OperationCanceledException</tt>.
+
 
+
 
+
 
+
 
+
 
+
  
 +
[https://eclipse.org/articles/Article-Progress-Monitors/article.html This article]
 +
offers some more useful examples.
  
 
== 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 Why should I use the new progress service?]]
  
 
+
{{Template:FAQ_Tagline}}
[[FAQ_How_do_I_use_a_%3Ctt%3ESubProgressMonitor%3C%2Ftt%3E%3F]]
+
 
+
 
+
[[FAQ_Why_should_I_use_the_new_progress_service%3F]]
+
 
+
<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>
+

Latest revision as of 11:30, 9 January 2020

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 more useful examples.

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.

Copyright © Eclipse Foundation, Inc. All Rights Reserved.