bundles/org.eclipse.platform.doc.isv/porting/4.6/recommended.html - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html lang="en">
 <head>
 <meta name="copyright" content="Copyright (c) 2015, 2016 IBM Corporation and others. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <meta http-equiv="Content-Style-Type" content="text/css">
 <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
 <title>Adopting Neon (4.6) mechanisms and APIs</title>
 </head>

 <body>

 <h1>Adopting Neon (4.6) mechanisms and APIs</h1>

 <p>
   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.
 </p>

 <ol>
 	<li><a href="#progress_convention">The calling conventions have changed for methods which receive a progress monitor</a></li>
 	<li><a href="#SubProgressMonitor">The class SubProgressMonitor has been deprecated and replaced by the class SubMonitor</a></li>
 	<li><a href="#ListenerList">ListenerList has been generified</a></li>
 	<li><a href="#FullScreen">Toggling Full-Screen</a></li>
 	<li><a href="#HighDPI">High-DPI icons</a></li>
 </ol>

 <hr>

 <!-- ############################################## -->
 <h2><a name="progress_convention">1. New calling convention for progress monitors</a></h2>

 <p><strong>What is affected:</strong>
 <p> All methods which receive an IProgressMonitor and all of their callers.</p>

 <p><strong>Description:</strong>
 <p>
 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 <code>done()</code> on IProgressMonitor rather than the
 receiver. Callers can choose to use SubMonitor, which doesn't required the use of
 <code>done()</code>. This means that - in practice - most
 invocations of <code>done()</code> will be deleted along with their surrounding try/catch blocks.
 <p>
 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.
 <p>
 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:

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

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

 <p>
 Fortunately there are few of these methods and they are easy to find.
 <p>
 <strong>Action required:</strong>
 <ul>
 <li>Open the call hierarchy view on StatusLineManager#getProgressMonitor().</li>
 <li>Ensure that all callers of these methods contain a finally block that
     invokes done (as in the doSaveAs() example, above).</li>
 <li>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.</li>
 <li>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().</li>
 </ul>

 <p><strong>More Information:</strong>
 <p>
 See <a href="https://eclipse.org/articles/Article-Progress-Monitors/article.html" target="_blank">this article</a> for
 more examples of how to use progress monitors with the new calling convention. Background and discussion
 about this change <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=487372" target="_blank">can be found here.</a>

 <!-- ############################################## -->
 <h2>2. <a name="SubProgressMonitor">SubProgressMonitor has been deprecated</a></h2>
 <p><strong>What is affected:</strong> Clients that refer to <code>org.eclipse.core.runtime.SubProgressMonitor</code>.</p>
 <p><strong>Description:</strong>
 <code>org.eclipse.core.runtime.SubProgressMonitor</code> has been deprecated and replaced by
 <code>org.eclipse.core.runtime.SubMonitor</code>.</p>
 <p><strong>Action required:</strong></p>
 <ul>
 <li>Calls to IProgressMonitor.beginTask on the root monitor should be replaced by a call to
 SubMonitor.convert.</li>
 <li>Keep the returned SubMonitor around as a local variable and refer to it instead of the
 root monitor for the remainder of the method.</li>
 <li>All calls to SubProgressMonitor(IProgressMonitor, int) should be replaced by calls to
 SubMonitor.split(int).</li>
 <li>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.</li>
 <li>It is not necessary to call done on an instance of SubMonitor.</li>
 </ul>

 <p><strong>Example:</strong>

 </p>
 Consider the following example:
 <pre>
      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();
         }
      }
 </pre>
 The above code should be refactored to this:
 <pre>
      void someMethod(IProgressMonitor pm) {
         SubMonitor subMonitor = SubMonitor.convert(pm, "Main Task", 100);
         doSomeWork(subMonitor.split(60));
         doSomeMoreWork(subMonitor.split(40));
      }
 </pre>

 <!-- ############################################## -->
 <h2>3. <a name="ListenerList">ListenerList has been generified</a></h2>
 <p><strong>What is affected:</strong> Clients that refer to <code>org.eclipse.core.runtime.ListenerList</code>.
 </p>
 <p><strong>Description:</strong>
 <code>org.eclipse.core.runtime.ListenerList</code> has been generified to offer compile-time type
 safety, to simplify client code, and to avoid giving clients access to an internal array.
 <code>ListenerList&lt;E&gt;</code> now implements <code>Iterable&lt;E&gt;</code>.
 </p>
 <p><strong>Action required:</strong>
 Clients should:
 </p>
 <ul>
 <li>add type arguments to their references to ListenerList</li>
 <li>convert usages of <code>#getListeners()</code> to an enhanced 'for' loop,
 thereby taking advantage of the type-safe <code>#iterator()</code>.</li>
 </ul>

 <!-- ############################################## -->
 <h2>4. <a name="FullScreen">Toggling Full-Screen command</a></h2>
 <p><strong>What is affected:</strong> Any code using the OS&nbsp;X-specific
 <code>org.eclipse.ui.cocoa.fullscreenWindow</code> command.

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

 <p><strong>Action required:</strong>
 Clients should convert usages to the
 <code>org.eclipse.ui.window.fullscreenmode</code> command.</p>

 <!-- ############################################## -->
 <h2>5. <a name="HighDPI">High-DPI icons</a></h2>
 <p><strong>What is affected:</strong> Products that use bitmap images.

 <p><strong>Description:</strong> On high-DPI screens, SWT now automatically
 scales images that have been created by one of the traditional constructors
 of <code>org.eclipse.swt.graphics.Image</code>. To avoid blurry images,
 clients can use one of these constructors:
 <ul><li><code>Image(Device, ImageFileNameProvider)</code></li>
     <li><code>Image(Device, ImageDataProvider)</code></li>
 </ul>
 <p>
 JFace-based applications that use the standard<br>
 <code>org.eclipse.jface.resource.ImageDescriptor#createFromURL(URL)</code><br>
 API to create icon images already support high-DPI icons out of the box:
 <p>
 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.
 <p>
 Example:<br>
 100%: newclass_wiz.png<br>
 200%: newclass_wiz@2x.png

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

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html lang="en">
	<head>
	<meta name="copyright" content="Copyright (c) 2015, 2016 IBM Corporation and others. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
	<title>Adopting Neon (4.6) mechanisms and APIs</title>
	</head>

	<body>

	<h1>Adopting Neon (4.6) mechanisms and APIs</h1>

	<p>
	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.
	</p>

	<ol>
	<li><a href="#progress_convention">The calling conventions have changed for methods which receive a progress monitor</a></li>
	<li><a href="#SubProgressMonitor">The class SubProgressMonitor has been deprecated and replaced by the class SubMonitor</a></li>
	<li><a href="#ListenerList">ListenerList has been generified</a></li>
	<li><a href="#FullScreen">Toggling Full-Screen</a></li>
	<li><a href="#HighDPI">High-DPI icons</a></li>
	</ol>

	<hr>

	<!-- ############################################## -->
	<h2><a name="progress_convention">1. New calling convention for progress monitors</a></h2>

	<p><strong>What is affected:</strong>
	<p> All methods which receive an IProgressMonitor and all of their callers.</p>

	<p><strong>Description:</strong>
	<p>
	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 <code>done()</code> on IProgressMonitor rather than the
	receiver. Callers can choose to use SubMonitor, which doesn't required the use of
	<code>done()</code>. This means that - in practice - most
	invocations of <code>done()</code> will be deleted along with their surrounding try/catch blocks.
	<p>
	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.
	<p>
	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:

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

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

	<p>
	Fortunately there are few of these methods and they are easy to find.
	<p>
	<strong>Action required:</strong>
	<ul>
	<li>Open the call hierarchy view on StatusLineManager#getProgressMonitor().</li>
	<li>Ensure that all callers of these methods contain a finally block that
	invokes done (as in the doSaveAs() example, above).</li>
	<li>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.</li>
	<li>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().</li>
	</ul>

	<p><strong>More Information:</strong>
	<p>
	See <a href="https://eclipse.org/articles/Article-Progress-Monitors/article.html" target="_blank">this article</a> for
	more examples of how to use progress monitors with the new calling convention. Background and discussion
	about this change <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=487372" target="_blank">can be found here.</a>

	<!-- ############################################## -->
	<h2>2. <a name="SubProgressMonitor">SubProgressMonitor has been deprecated</a></h2>
	<p><strong>What is affected:</strong> Clients that refer to <code>org.eclipse.core.runtime.SubProgressMonitor</code>.</p>
	<p><strong>Description:</strong>
	<code>org.eclipse.core.runtime.SubProgressMonitor</code> has been deprecated and replaced by
	<code>org.eclipse.core.runtime.SubMonitor</code>.</p>
	<p><strong>Action required:</strong></p>
	<ul>
	<li>Calls to IProgressMonitor.beginTask on the root monitor should be replaced by a call to
	SubMonitor.convert.</li>
	<li>Keep the returned SubMonitor around as a local variable and refer to it instead of the
	root monitor for the remainder of the method.</li>
	<li>All calls to SubProgressMonitor(IProgressMonitor, int) should be replaced by calls to
	SubMonitor.split(int).</li>
	<li>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.</li>
	<li>It is not necessary to call done on an instance of SubMonitor.</li>
	</ul>

	<p><strong>Example:</strong>

	</p>
	Consider the following example:
	<pre>
	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();
	}
	}
	</pre>
	The above code should be refactored to this:
	<pre>
	void someMethod(IProgressMonitor pm) {
	SubMonitor subMonitor = SubMonitor.convert(pm, "Main Task", 100);
	doSomeWork(subMonitor.split(60));
	doSomeMoreWork(subMonitor.split(40));
	}
	</pre>

	<!-- ############################################## -->
	<h2>3. <a name="ListenerList">ListenerList has been generified</a></h2>
	<p><strong>What is affected:</strong> Clients that refer to <code>org.eclipse.core.runtime.ListenerList</code>.
	</p>
	<p><strong>Description:</strong>
	<code>org.eclipse.core.runtime.ListenerList</code> has been generified to offer compile-time type
	safety, to simplify client code, and to avoid giving clients access to an internal array.
	<code>ListenerList<E></code> now implements <code>Iterable<E></code>.
	</p>
	<p><strong>Action required:</strong>
	Clients should:
	</p>
	<ul>
	<li>add type arguments to their references to ListenerList</li>
	<li>convert usages of <code>#getListeners()</code> to an enhanced 'for' loop,
	thereby taking advantage of the type-safe <code>#iterator()</code>.</li>
	</ul>

	<!-- ############################################## -->
	<h2>4. <a name="FullScreen">Toggling Full-Screen command</a></h2>
	<p><strong>What is affected:</strong> Any code using the OS X-specific
	<code>org.eclipse.ui.cocoa.fullscreenWindow</code> command.

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

	<p><strong>Action required:</strong>
	Clients should convert usages to the
	<code>org.eclipse.ui.window.fullscreenmode</code> command.</p>

	<!-- ############################################## -->
	<h2>5. <a name="HighDPI">High-DPI icons</a></h2>
	<p><strong>What is affected:</strong> Products that use bitmap images.

	<p><strong>Description:</strong> On high-DPI screens, SWT now automatically
	scales images that have been created by one of the traditional constructors
	of <code>org.eclipse.swt.graphics.Image</code>. To avoid blurry images,
	clients can use one of these constructors:
	<ul><li><code>Image(Device, ImageFileNameProvider)</code></li>
	<li><code>Image(Device, ImageDataProvider)</code></li>
	</ul>
	<p>
	JFace-based applications that use the standard<br>
	<code>org.eclipse.jface.resource.ImageDescriptor#createFromURL(URL)</code><br>
	API to create icon images already support high-DPI icons out of the box:
	<p>
	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.
	<p>
	Example:<br>
	100%: newclass_wiz.png<br>
	200%: newclass_wiz@2x.png

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

	</body>
	</html>