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.
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’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> | <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> | </pre> | ||
| − | |||
| − | |||
| − | |||
The monitor can also be used to respond to cancellation requests. | 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: == | == 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}} | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
Latest revision as of 12: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’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:
- The Using Progress Monitors article offers more useful examples
- FAQ How do I use a SubProgressMonitor?
- FAQ Why should I use the new progress service?
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.