Adopting Neon (4.6) mechanisms and APIs

This section describes changes that are required if you are trying to change your 4.5 plug-in to adopt the 4.6 mechanisms and APIs.

The calling conventions have changed for methods which receive a progress monitor
The class SubProgressMonitor has been deprecated and replaced by the class SubMonitor
ListenerList has been generified
Toggling Full-Screen
High-DPI icons

1. New calling convention for progress monitors

What is affected:

All methods which receive an IProgressMonitor and all of their callers.

Description:

In order to reduce boilerplate, Eclipse 4.7 will introduce a new calling convention for methods which receive an IProgressMonitor as a parameter. In Eclipse 4.7 it will be the caller's responsibility to invoke done() on IProgressMonitor rather than the receiver. Callers can choose to use SubMonitor, which doesn't required the use of done(). This means that - in practice - most invocations of done() will be deleted along with their surrounding try/catch blocks.

Clients should not remove the boilerplate yet. For now, any method that previously received an IProgressMonitor and invoked done() on it should continue to do so.

Methods which obtain their own top-level progress monitors rather than receiving one as a parameter are now responsible for invoking done() on those monitors. Technically, they were always responsible for doing this, but some of them didn't do so because any method they passed it to would have invoked done() on their behalf. Now this will matter and the methods will need to be changed. For example:

// Before:
public void doSaveAs() {
  IProgressMonitor monitor= getProgressMonitor();
  performSaveAs(monitor);
}

// After:
public void doSaveAs() {
  IProgressMonitor monitor= getProgressMonitor();
    try {
      performSaveAs(monitor);
    } finally {
      monitor.done();
    }
}

Fortunately there are few of these methods and they are easy to find.

Action required:

Open the call hierarchy view on StatusLineManager#getProgressMonitor().
Ensure that all callers of these methods contain a finally block that invokes done (as in the doSaveAs() example, above).
Open the type hierarchy of IProgressMonitor. Look for progress monitors which do something in their done() method besides reporting work, setting a task name, or calling done on another monitor. SubMonitor can be ignored. Monitors which set a control's visibility or deallocate a resource in their done() method must not be ignored.
Use the call hierarchy view to locate every place that instantiates or accesses an instance of one of those classes. Ensure that those access points contain a try/finally block that invokes done().

More Information:

See this article for more examples of how to use progress monitors with the new calling convention. Background and discussion about this change can be found here.

2. SubProgressMonitor has been deprecated

What is affected: Clients that refer to org.eclipse.core.runtime.SubProgressMonitor.

Description: org.eclipse.core.runtime.SubProgressMonitor has been deprecated and replaced by org.eclipse.core.runtime.SubMonitor.

Action required:

Calls to IProgressMonitor.beginTask on the root monitor should be replaced by a call to SubMonitor.convert.
Keep the returned SubMonitor around as a local variable and refer to it instead of the root monitor for the remainder of the method.
All calls to SubProgressMonitor(IProgressMonitor, int) should be replaced by calls to SubMonitor.split(int).
If a SubProgressMonitor is constructed using the SUPPRESS_SUBTASK_LABEL flag, replace it with the two-argument version of SubMonitor.split(int, int) using SubMonitor.SUPPRESS_SUBTASK as the second argument.
It is not necessary to call done on an instance of SubMonitor.

Example:

Consider the following example:

     void someMethod(IProgressMonitor pm) {
        pm.beginTask("Main Task", 100);
        SubProgressMonitor subMonitor1= new SubProgressMonitor(pm, 60);
        try {
           doSomeWork(subMonitor1);
        } finally {
           subMonitor1.done();
        }
        SubProgressMonitor subMonitor2= new SubProgressMonitor(pm, 40);
        try {
           doSomeMoreWork(subMonitor2);
        } finally {
           subMonitor2.done();
        }
     }

The above code should be refactored to this:

     void someMethod(IProgressMonitor pm) {
        SubMonitor subMonitor = SubMonitor.convert(pm, "Main Task", 100);
        doSomeWork(subMonitor.split(60));
        doSomeMoreWork(subMonitor.split(40));
     }

3. ListenerList has been generified

What is affected: Clients that refer to org.eclipse.core.runtime.ListenerList.

Description: org.eclipse.core.runtime.ListenerList has been generified to offer compile-time type safety, to simplify client code, and to avoid giving clients access to an internal array. ListenerList<E> now implements Iterable<E>.

Action required: Clients should:

add type arguments to their references to ListenerList
convert usages of #getListeners() to an enhanced 'for' loop, thereby taking advantage of the type-safe #iterator().

4. Toggling Full-Screen command

What is affected: Any code using the OS X-specific org.eclipse.ui.cocoa.fullscreenWindow command.

Description: Eclipse Platform 4.2 introduced an OS X-specific command to toggle full-screen mode for the current window called org.eclipse.ui.cocoa.fullscreenWindow, bound to Command-Ctrl-F. In 4.6 we introduced a cross-platform command to toggle full-screen called org.eclipse.ui.window.fullscreenmode (bugs 489087, 491572). As a result, we have two "Toggle Full Screen" commands on OS X, and both appear in the Quick Access. The use of org.eclipse.ui.cocoa.fullscreenWindow is now deprecated, and developers should use the org.eclipse.ui.window.fullscreenmode command instead.

Action required: Clients should convert usages to the org.eclipse.ui.window.fullscreenmode command.

5. High-DPI icons

What is affected: Products that use bitmap images.

Description: On high-DPI screens, SWT now automatically scales images that have been created by one of the traditional constructors of org.eclipse.swt.graphics.Image. To avoid blurry images, clients can use one of these constructors:

Image(Device, ImageFileNameProvider)
Image(Device, ImageDataProvider)

JFace-based applications that use the standard
org.eclipse.jface.resource.ImageDescriptor#createFromURL(URL)
API to create icon images already support high-DPI icons out of the box:

Just append "@2x" to the file name and place the high-DPI icons into the same folder as the original icon. If you use OSGi bundles, you can also put the icons into a fragment that contains the same folder structure.

Example:
100%: newclass_wiz.png
200%: newclass_wiz@2x.png

Action required: In JFace applications, add "@2x" icons. In SWT applications, use the new Image constructors.