Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

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

(→‎See Also:)
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
+
−
to throw <tt>OperationCanceledException</tt>.
+
  
 
== See Also: ==
 
== See Also: ==

Revision as of 13:18, 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.

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.
Retrieved from "https://wiki.eclipse.org/index.php?title=FAQ_How_do_I_use_progress_monitors%3F&oldid=404313"

Back to the top