| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | |
| <html> | |
| <head> | |
| <title>Rich Client Platform</title> | |
| <link href="../default_style.css" rel="stylesheet"> | |
| <link href="java2html.css" rel="stylesheet"> | |
| </head> | |
| <body> | |
| <div align="right"><font face="Times New Roman, Times, serif" size="2">Copyright | |
| © 2004-2006 Ed Burnette.</font> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tbody> | |
| <tr> | |
| <td align="left" valign="top" colspan="2" bgcolor="#0080c0"><b><font | |
| face="Arial,Helvetica"><font color="#ffffff">Eclipse Article</font></font></b></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <div align="left"> | |
| <h1 title="RCP Tutorial"><img src="../images/Idea.jpg" align="middle" | |
| width="120" height="86" alt=""></h1> | |
| </div> | |
| <h1 align="center">Rich Client Tutorial Part 2</h1> | |
| <p class="summary">The Rich Client Platform (RCP) allows you to build | |
| Java applications that can compete with native applications on any | |
| platform. Part 1 of the tutorial introduced you to the platform and the | |
| steps used to build the smallest possible RCP program. In part 2 we'll | |
| look at what we did in more detail and introduce some of the | |
| configuration classes that let you take control of much of the layout | |
| and functionality of an RCP application. This part has been updated for | |
| Eclipse 3.1.2</p> | |
| <p><b>By Ed Burnette, SAS</b><br> | |
| <font size="-1">August 9, 2004<br> | |
| <font size="-1"><b>Updated for 3.1.2:</b> February 6, 2006</font> </font></p> | |
| <hr width="100%"> | |
| <h2>Introduction</h2> | |
| <p>In early versions of Eclipse, many functions of the IDE were | |
| hard-wired into the code. These included the name and location of the | |
| File menu, the title of the Workbench Window, and the existence of the | |
| status bar. This was fine for the IDE but when people started to use | |
| Eclipse as a basis for non-IDE programs, sometimes these things didn't | |
| make sense. Although all the source code was provided, it was | |
| inconvenient to find the right places that had to be changed.</p> | |
| <p>So, beginning in Eclipse 3.0, the designers refactored the API to | |
| make these and other hard-wired aspects of the user interface | |
| controllable through public API. Subsequent releases have fine tuned | |
| that API and provided tooling in the Plug-in Development Environment | |
| (PDE) to lower the barriers to getting started using it. However, you'll | |
| eventually need to look behind the PDE wizards and editors to really | |
| understand what is going on.</p> | |
| <p>In this part we'll examine the code and configuration files created | |
| in Part 1 of the tutorial. To keep the parts separate I've recreated the | |
| examples for each part under a different name. All the sample code for | |
| Part 2 may be found in the <a href="part2.zip">part2.zip archive file</a>. | |
| </p> | |
| <p><img src="../images/note.gif" alt="Note: " width="62" height="13"> If | |
| you're following along with this tutorial in Eclipse and you're thinking | |
| of just renaming your old project, I don't recommend it. In Eclipse 3.1, | |
| Refactor > Rename does not work well on plug-in projects due to all | |
| the internal references in XML files and strings that don't participate. | |
| Hopefully this will be fixed in a future release.</p> | |
| <p>Before we go any further let's clear up some possible confusion about | |
| the relationship between Applications, Workbenches, and Workbench | |
| Windows.</p> | |
| <h2>Applications, Workbenches, and Workbench Windows</h2> | |
| <p>The Application is a class you create that acts as your RCP program's | |
| main routine. You can think of it as the controller for the program. | |
| Just like the controller in a Model2 architecture, it is short and sweet | |
| and doesn't change significantly for different projects. All it does is | |
| create a Workbench and attach another class called a Workbench Advisor | |
| to it (Workbench Advisors will be covered more later).</p> | |
| <p>The Workbench is declared and maintained for you as part of the RCP | |
| framework. There is only one Workbench but it can have more than one | |
| visible top-level Workbench Window. For example, in the Eclipse IDE, | |
| when you first start Eclipse you will see one Workbench Window, but if | |
| you select <b>Window > New Window</b> a second window pops up -- two | |
| Workbench Windows, but only one Workbench.</p> | |
| <p>Ok, now that that's out of the way, let's see what those PDE wizards | |
| did for us, starting with the plug-in manifest.</p> | |
| <h2>Plug-in manifest</h2> | |
| <p>The plug-in manifest ties all the code and resources together. When | |
| you first create a plug-in, Eclipse will create and open the manifest | |
| for you automatically. The manifest is split into two files: MANIFEST.MF | |
| and plugin.xml. PDE provides a fancy editor to modify the options stored | |
| in these files (see Figure 1) but also allows you to edit the source | |
| directly.</p> | |
| <img src="images/manifest-editor-overview_s.png" alt=""> | |
| <p><b> Figure 1. The plug-in manifest editor provides a single interface | |
| for editing the manifest and related files. The tabs along the bottom of | |
| the editor access all the different sections in the GUI or the raw text | |
| files.</b></p> | |
| <h3>MANIFEST.MF</h3> | |
| <p>The OSGi bundle manifest is stored in MANIFEST.MF. OSGi is the name | |
| of a standard that Eclipse uses for dynamically loading plug-ins (see | |
| refererences). Listing 1 shows the OSGi bundle manifest generated by the | |
| plug-in wizard. Everything in this file can be edited by the Manifest | |
| editor, so there should be no need to edit it by hand. However if you | |
| need to, just double-click it in the Package Explorer to bring up the | |
| Manifest editor, then click on the MANIFEST.MF tab in the editor to see | |
| and modify the source.</p> | |
| <p><img src="../images/note.gif" alt="Note: " width="62" height="13"> | |
| For backwards compatability with Eclipse 2.1, Eclipse will recognize and | |
| load plug-ins that do not use MANIFEST.MF. However, this incurs a small | |
| performance penalty and is not recommended for plug-ins targeting | |
| Eclipse 3.0 and later.</p> | |
| <p><b>Listing 1. MANIFEST.MF </b></p> | |
| <pre> | |
| Manifest-Version: <font class="java5">1.0</font> | |
| Bundle-ManifestVersion: <font class="java5">2</font> | |
| Bundle-Name: <font class="java5">Part2 Plug-in</font> | |
| Bundle-SymbolicName: <font class="java5">org.eclipse.ui.tutorials.rcp.part2; singleton:=true</font> | |
| Bundle-Version: <font class="java5">1.0.0</font> | |
| Bundle-Activator: <font class="java5">org.eclipse.ui.tutorials.rcp.part2.Part2Plugin</font> | |
| Bundle-Localization: <font class="java5">plugin</font> | |
| Require-Bundle: <font class="java5">org.eclipse.ui, | |
| org.eclipse.core.runtime</font> | |
| Eclipse-AutoStart: <font class="java5">true</font> | |
| </pre> | |
| <h3>plugin.xml</h3> | |
| <p>The Eclipse extension manifest is called plugin.xml. It's used for | |
| defining and using Eclipse extension points, so if you're not using | |
| extension points then this file may be omitted. Extension points are the | |
| fundamental way that Eclipse plug-ins are tied together so if you're not | |
| familiar with them see one of the articles in the Reference section. | |
| Listing 2 shows the plugin.xml file created by the PDE wizard.</p> | |
| <p><b>Listing 2. plugin.xml </b></p> | |
| <pre> | |
| <?xml version="1.0" encoding="UTF-8"?> | |
| <?eclipse version="3.0"?> | |
| <plugin> | |
| <extension | |
| id=<font class="java5">"application"</font> | |
| point=<font class="java5">"org.eclipse.core.runtime.applications"</font>> | |
| <application> | |
| <run | |
| class=<font class="java5">"org.eclipse.ui.tutorials.rcp.part2.Application"</font>> | |
| </run> | |
| </application> | |
| </extension> | |
| <extension | |
| point=<font class="java5">"org.eclipse.ui.perspectives"</font>> | |
| <perspective | |
| name=<font class="java5">"Part2 Perspective"</font> | |
| class=<font class="java5">"org.eclipse.ui.tutorials.rcp.part2.Perspective"</font> | |
| id=<font class="java5">"org.eclipse.ui.tutorials.rcp.part2.perspective"</font>> | |
| </perspective> | |
| </extension> | |
| <extension | |
| id=<font class="java5">"product"</font> | |
| point=<font class="java5">"org.eclipse.core.runtime.products"</font>> | |
| <product | |
| application=<font class="java5">"org.eclipse.ui.tutorials.rcp.part2.application"</font> | |
| name=<font class="java5">"RCP Tutorial 2"</font>/> | |
| </extension> | |
| </plugin> | |
| </pre> | |
| <p>The class name of the main program is defined with the <code>org.eclipse.core.runtime.applications</code> | |
| extension.</p> | |
| <p><img src="../images/note.gif" alt="Note: " width="62" height="13"> | |
| Although it's not an absolute requirement, I recommend keeping your id's | |
| and your class names the same except possibly for case. For historical | |
| reasons, Eclipse prepends the plug-in's id to the id of your top level | |
| plug-in elements (like <code>extension</code>). For example, even though | |
| the plugin.xml in listing 2 says <code>id="application"</code>, the | |
| fully qualified id for that extension is <code>org.eclipse.ui.tutorials.rcp.part2.application</code>. | |
| Since the perspective's id is written on a sub-element (<code>perspective</code>) | |
| it has to be spelled out completely in the manifest (<code>org.eclipse.ui.tutorials.rcp.part2.perspective</code>). | |
| By convention only, package names and ids are lower case and class names are Pascal Case. | |
| </p> | |
| <h2>The main program</h2> | |
| <p>The <code>org.eclipse.core.runtime.applications</code> extension | |
| tells the Eclipse runtime the name of your main program. This is a class | |
| that implements <code>IPlatformRunnable</code> and a <code>run()</code> | |
| method. Listing 3 shows the simple implementation supplied by the | |
| plug-in wizard.</p> | |
| <p><b>Listing 3. Application.java </b></p> | |
| <tt class="java"><font class="java4">package </font><font class="java10">org.eclipse.ui.tutorials.rcp.part2;<br /> | |
| <br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.core.runtime.IPlatformRunnable;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.swt.widgets.Display;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.PlatformUI;<br /> | |
| <br /> | |
| </font><font class="java14">/**<br /> | |
| * This class controls all aspects of the application's execution<br /> | |
| */<br /> | |
| </font><font class="java4">public class </font><font class="java10">Application | |
| </font><font class="java4">implements </font><font class="java10">IPlatformRunnable | |
| </font><font class="java8">{<br /> | |
| <br /> | |
|   </font><font class="java2">/* (non-Javadoc)<br /> | |
|    * @see | |
| org.eclipse.core.runtime.IPlatformRunnable#run(java.lang.Object)<br /> | |
|    */<br /> | |
|   </font><font class="java4">public </font><font class="java10">Object | |
| run</font><font class="java8">(</font><font class="java10">Object args</font><font | |
| class="java8">) </font><font class="java4">throws </font><font | |
| class="java10">Exception </font><font class="java8">{<br /> | |
|     </font><font class="java10">Display display = | |
| PlatformUI.createDisplay</font><font class="java8">()</font><font | |
| class="java10">;<br /> | |
|     </font><font class="java4">try </font><font | |
| class="java8">{<br /> | |
|       </font><font class="java9">int </font><font | |
| class="java10">returnCode = PlatformUI.createAndRunWorkbench</font><font | |
| class="java8">(</font><font class="java10">display, </font><font | |
| class="java4">new </font><font class="java10">ApplicationWorkbenchAdvisor</font><font | |
| class="java8">())</font><font class="java10">;<br /> | |
|       </font><font class="java4">if </font><font | |
| class="java8">(</font><font class="java10">returnCode == | |
| PlatformUI.RETURN_RESTART</font><font class="java8">) {<br /> | |
|         </font><font class="java4">return | |
| </font><font class="java10">IPlatformRunnable.EXIT_RESTART;<br /> | |
|       </font><font class="java8">}<br /> | |
|       </font><font class="java4">return </font><font | |
| class="java10">IPlatformRunnable.EXIT_OK;<br /> | |
|     </font><font class="java8">} </font><font | |
| class="java4">finally </font><font class="java8">{<br /> | |
|       </font><font class="java10">display.dispose</font><font | |
| class="java8">()</font><font class="java10">;<br /> | |
|     </font><font class="java8">}<br /> | |
|   }<br /> | |
| }</font></tt> | |
| <h2>The default perspective</h2> | |
| <p>A Perspective is a set of visible views, editors, and menus including | |
| their positions and sizes. In an RCP program you must define at least | |
| one perspective and make it the default. Perspectives are created by | |
| implementing <code>IPerspectiveFactory</code> using the class name | |
| referred to by the <code>org.eclipse.ui.perspectives</code> extension. | |
| See Listing 4 for the implementation provided by the plug-in wizard. The | |
| important part of this interface is the <code>createInitialLayout()</code> | |
| method where you position and open any views and/or editors you'd like | |
| the user to start with. So far in this example we haven't created any | |
| views so it's a pretty boring perspective.</p> | |
| <p><b>Listing 4. Perspective.java </b></p> | |
| <tt class="java"><font class="java4">package </font><font class="java10">org.eclipse.ui.tutorials.rcp.part2;<br /> | |
| <br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.IPageLayout;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.IPerspectiveFactory;<br /> | |
| <br /> | |
| </font><font class="java4">public class </font><font class="java10">Perspective | |
| </font><font class="java4">implements </font><font class="java10">IPerspectiveFactory | |
| </font><font class="java8">{<br /> | |
| <br /> | |
|   </font><font class="java4">public </font><font class="java9">void | |
| </font><font class="java10">createInitialLayout</font><font | |
| class="java8">(</font><font class="java10">IPageLayout layout</font><font | |
| class="java8">) {<br /> | |
|   }<br /> | |
| }</font></tt> | |
| <h2>The Advisor classes</h2> | |
| <p>The main program referenced a class called <code>ApplicationWorkbenchAdvisor</code>. | |
| This is one of three Advisor classes that you use to configure all | |
| aspects of the Workbench such as the title, menu bars, and so on. <b>These | |
| are the most important classes for an RCP developer to understand.</b> | |
| You extend the base version of the class, for example <code>WorkbenchAdvisor</code>, | |
| in your RCP application and override one or more of the methods to set | |
| whatever options you want. Let's examine these classes now in more | |
| detail.</p> | |
| <h3>Workbench Advisor</h3> | |
| <p>Methods in this class are called from the platform to notify you at | |
| every point in the lifecycle of the Workbench. They also provide a way | |
| to handle exceptions in the event loop, and provide important parameters | |
| to the Workbench such as the default perspective. With the exception of | |
| <code>createWorkbenchWindowAdvisor()</code> and <code>getInitialWindowPerspectiveId()</code>, | |
| the methods on <code>WorkbenchAdvisor</code> do not have to be | |
| overridden. Listing 5 shows the implementation that was provided by the | |
| plug-in wizard.</p> | |
| <p><b>Listing 5. ApplicationWorkbenchAdvisor.java </b></p> | |
| <tt class="java"><font class="java4">package </font><font class="java10">org.eclipse.ui.tutorials.rcp.part2;<br /> | |
| <br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.application.IWorkbenchWindowConfigurer;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.application.WorkbenchAdvisor;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.application.WorkbenchWindowAdvisor;<br /> | |
| <br /> | |
| </font><font class="java4">public class </font><font class="java10">ApplicationWorkbenchAdvisor | |
| </font><font class="java4">extends </font><font class="java10">WorkbenchAdvisor | |
| </font><font class="java8">{<br /> | |
| <br /> | |
|   </font><font class="java4">private static final </font><font | |
| class="java10">String PERSPECTIVE_ID = </font><font class="java5">"org.eclipse.ui.tutorials.rcp.part2.perspective"</font><font | |
| class="java10">;<br /> | |
| <br /> | |
|     </font><font class="java4">public </font><font | |
| class="java10">WorkbenchWindowAdvisor createWorkbenchWindowAdvisor</font><font | |
| class="java8">(</font><font class="java10">IWorkbenchWindowConfigurer | |
| configurer</font><font class="java8">) {<br /> | |
|         </font><font class="java4">return | |
| new </font><font class="java10">ApplicationWorkbenchWindowAdvisor</font><font | |
| class="java8">(</font><font class="java10">configurer</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|     </font><font class="java8">}<br /> | |
| <br /> | |
|   </font><font class="java4">public </font><font class="java10">String | |
| getInitialWindowPerspectiveId</font><font class="java8">() {<br /> | |
|     </font><font class="java4">return </font><font | |
| class="java10">PERSPECTIVE_ID;<br /> | |
|   </font><font class="java8">}<br /> | |
| }</font></tt> | |
| <p><img src="../images/note.gif" alt="Note: " width="62" height="13"> | |
| Why not an interface? You'll notice that <code>WorkbenchAdvisor</code> | |
| is an abstract class. For the most part, Eclipse APIs shun abstract | |
| classes in favor of interfaces and base classes that implement those | |
| interfaces. In this case, the designers intend for <code>WorkbenchAdvisor</code> | |
| to <i>always</i> be implemented by the RCP application, and the base | |
| class doesn't contain any significant functionality. Also it is very | |
| likely that new methods will need to be added to the base class in the | |
| future (something that is difficult using interfaces). So this was a | |
| deliberate design choice. See the article on evolving Java APIs in the | |
| reference section for more tips.</p> | |
| <h4>Workbench lifecycle hooks</h4> | |
| <p>The Workbench Advisor class has several methods that are called at | |
| defined points in the Workbench's lifecycle (see Table 1). By overriding | |
| these you can run whatever code you want at these points.</p> | |
| <p><b>Table 1. Workbench lifecycle hooks provided by <code>WorkbenchAdvisor</code>. | |
| </b></p> | |
| <table border="1"> | |
| <tr> | |
| <th>Method</th> | |
| <th>Description</th> | |
| <th>Parameter(s)</th> | |
| </tr> | |
| <tr> | |
| <td>initialize</td> | |
| <td>Called first to perform any setup such as parsing the command | |
| line, registering adapters, declaring images, etc..</td> | |
| <td><code>IWorkbenchConfigurer</code></td> | |
| </tr> | |
| <tr> | |
| <td>preStartup</td> | |
| <td>Called after initialization but before the first window is opened. | |
| May be used to set options affecting which editors and views are | |
| initially opened.</td> | |
| <td> </td> | |
| </tr> | |
| <tr> | |
| <td>postStartup</td> | |
| <td>Called after all windows have been opened or restored, but before | |
| the event loop starts. It can be used to start automatic processes and | |
| to open tips or other windows.</td> | |
| <td> </td> | |
| </tr> | |
| <tr> | |
| <td>preShutdown</td> | |
| <td>Called after the event loop has terminated but before any windows | |
| have been closed.</td> | |
| <td> </td> | |
| </tr> | |
| <tr> | |
| <td>postShutdown</td> | |
| <td>Called after all windows are closed during Workbench shutdown. | |
| This can be used to save the current application state and clean up | |
| anything created by <code>initialize</code>.</td> | |
| <td> </td> | |
| </tr> | |
| </table> | |
| <h4>Event loop hooks</h4> | |
| <p>The event loop is the code that is running most of the time during | |
| the life of the Workbench. It handles all user inputs and dispatches | |
| them to the right listeners. RCP provides a couple of hooks to handle | |
| crashes and perform work during idle time (see Table 2). Note however | |
| that the Jobs interface (see References) is a better way of performing | |
| long running work than this idle hook.</p> | |
| <p><b>Table 2. Event loop hooks provided by <code>WorkbenchAdvisor</code>. | |
| </b></p> | |
| <table border="1"> | |
| <tr> | |
| <th>Method</th> | |
| <th>Description</th> | |
| <th>Parameter(s)</th> | |
| </tr> | |
| <tr> | |
| <td>eventLoopException</td> | |
| <td>Called if there is an unhandled exception in the event loop. The | |
| default implementation will log the error.</td> | |
| <td><code>Throwable</code></td> | |
| </tr> | |
| <tr> | |
| <td>eventLoopIdle</td> | |
| <td>Called when the event loop has nothing to do.</td> | |
| <td><code>Display</code></td> | |
| </tr> | |
| </table> | |
| <h4>Information getting hooks</h4> | |
| <p>Next, there are few methods you can implement that the platform will | |
| call to get information about your application (see Table 3). The most | |
| important one (and the only one that is not optional) is <code>getInitialWindowPerspectiveId</code>. | |
| We used this in Listing 5 to return the id of the starting perspective.</p> | |
| <p><b>Table 3. Information request methods you can override in <code>WorkbenchAdvisor</code>. | |
| </b></p> | |
| <table border="1"> | |
| <tr> | |
| <th>Method</th> | |
| <th>Description</th> | |
| <th>Parameter(s)</th> | |
| </tr> | |
| <tr> | |
| <td>getDefaultPageInput</td> | |
| <td>Return the default input for new workbench pages. Defaults to | |
| null.</td> | |
| <td> </td> | |
| </tr> | |
| <tr> | |
| <td>getInitialWindowPerspectiveId</td> | |
| <td>Return the initial perspective used for new workbench windows. | |
| This is a required function that has no default.</td> | |
| <td> </td> | |
| </tr> | |
| <tr> | |
| <td>getMainPreferencePageId</td> | |
| <td>Return the preference page that should be displayed first. | |
| Defaults to null, meaning the pages should be arranged alphabetically. | |
| </td> | |
| <td> </td> | |
| </tr> | |
| </table> | |
| <h4>Advanced configuration</h4> | |
| <p>The <code>WorkbenchAdvisor</code> events above should be sufficient | |
| for most applications, but just in case, RCP provides another method to | |
| take complete control of how your application windows and controls are | |
| created. It's listed in Table 4 for completeness but I don't expect many | |
| programs will need it.</p> | |
| <p><b>Table 4. Advanced methods in <code>org.eclipse.ui.application.WorkbenchAdvisor</code>. | |
| </b></p> | |
| <table border="1"> | |
| <tr> | |
| <th>Method</th> | |
| <th>Description</th> | |
| <th>Parameter(s)</th> | |
| </tr> | |
| <tr> | |
| <td>openWindows</td> | |
| <td>Open all Workbench windows on startup. The default implementation | |
| tries to restore the previously saved workbench state.</td> | |
| <td> </td> | |
| </tr> | |
| </table> | |
| <h3>Workbench Window Advisor</h3> | |
| <p>This class is used to control the status line, toolbar, title, window | |
| size, and other things you'll almost certainly want to customize. You | |
| can also use it to hook into all the various lifecycle events of the | |
| Workbench Windows. Listing 6 shows the implementation provided by the | |
| plug-in wizard.</p> | |
| <p><b>Listing 6. ApplicationWorkbenchWindowAdvisor.java </b></p> | |
| <tt class="java"><font class="java4">package </font><font class="java10">org.eclipse.ui.tutorials.rcp.part2;<br /> | |
| <br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.swt.graphics.Point;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.application.ActionBarAdvisor;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.application.IActionBarConfigurer;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.application.IWorkbenchWindowConfigurer;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.application.WorkbenchWindowAdvisor;<br /> | |
| <br /> | |
| </font><font class="java4">public class </font><font class="java10">ApplicationWorkbenchWindowAdvisor | |
| </font><font class="java4">extends </font><font class="java10">WorkbenchWindowAdvisor | |
| </font><font class="java8">{<br /> | |
| <br /> | |
|     </font><font class="java4">public </font><font | |
| class="java10">ApplicationWorkbenchWindowAdvisor</font><font | |
| class="java8">(</font><font class="java10">IWorkbenchWindowConfigurer | |
| configurer</font><font class="java8">) {<br /> | |
|         </font><font class="java4">super</font><font | |
| class="java8">(</font><font class="java10">configurer</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|     </font><font class="java8">}<br /> | |
| <br /> | |
|     </font><font class="java4">public </font><font | |
| class="java10">ActionBarAdvisor createActionBarAdvisor</font><font | |
| class="java8">(</font><font class="java10">IActionBarConfigurer | |
| configurer</font><font class="java8">) {<br /> | |
|         </font><font class="java4">return | |
| new </font><font class="java10">ApplicationActionBarAdvisor</font><font | |
| class="java8">(</font><font class="java10">configurer</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|     </font><font class="java8">}<br /> | |
|     <br /> | |
|     </font><font class="java4">public </font><font | |
| class="java9">void </font><font class="java10">preWindowOpen</font><font | |
| class="java8">() {<br /> | |
|         </font><font class="java10">IWorkbenchWindowConfigurer | |
| configurer = getWindowConfigurer</font><font class="java8">()</font><font | |
| class="java10">;<br /> | |
|         configurer.setInitialSize</font><font | |
| class="java8">(</font><font class="java4">new </font><font | |
| class="java10">Point</font><font class="java8">(</font><font | |
| class="java7">400</font><font class="java10">, </font><font | |
| class="java7">300</font><font class="java8">))</font><font | |
| class="java10">;<br /> | |
|         configurer.setShowCoolBar</font><font | |
| class="java8">(</font><font class="java4">false</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         configurer.setShowStatusLine</font><font | |
| class="java8">(</font><font class="java4">false</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         configurer.setTitle</font><font | |
| class="java8">(</font><font class="java5">"Hello RCP"</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|     </font><font class="java8">}<br /> | |
| }</font></tt> | |
| <p>Methods on WorkbenchWindowAdvisor (see Table 5 and Table 6) will all | |
| need access to a Configurer interface (in this case, <code>IWorkbenchWindowConfigurer</code>) | |
| in order to do anything so they're expected to call <code>getWindowConfigurer()</code> | |
| to fetch it. You call methods on the Configurer interfaces to actually | |
| change the options. These interfaces are not covered in any detail in | |
| this tutorial but you can refer to their Javadoc for more information.</p> | |
| <p><b>Table 5. Workbench window lifecycle hooks provided by <code>WorkbenchWindowAdvisor</code>. | |
| </b></p> | |
| <table border="1"> | |
| <tr> | |
| <th>Method</th> | |
| <th>Description</th> | |
| <th>Parameter(s)</th> | |
| </tr> | |
| <tr> | |
| <td>preWindowOpen</td> | |
| <td>Called in the constructor of the Workbench Window. Use this method | |
| to set options such as whether or not the window will have a menu bar. | |
| However none of the window's widgets have been created yet so they | |
| can't be referenced in this method.</td> | |
| <td><code></code></td> | |
| </tr> | |
| <tr> | |
| <td>postWindowRestore</td> | |
| <td>Optionally called for cases when a window has been restored from | |
| saved state but before it is opened.</td> | |
| <td><code></code></td> | |
| </tr> | |
| <tr> | |
| <td>postWindowCreate</td> | |
| <td>Called after a window has been restored from saved state or | |
| created from scratch but before it is opened.</td> | |
| <td><code></code></td> | |
| </tr> | |
| <tr> | |
| <td>openIntro</td> | |
| <td>Called immediately before a window is opened in order to create | |
| the Intro component (if any).</td> | |
| <td><code></code></td> | |
| </tr> | |
| <tr> | |
| <td>postWindowOpen</td> | |
| <td>Called right after the Workbench window is opened. Can be used to | |
| tweak any of the window's widgets, for example to set a title or | |
| change its size.</td> | |
| <td><code></code></td> | |
| </tr> | |
| <tr> | |
| <td>preWindowShellClose</td> | |
| <td>Called before the Workbench window is closed (technically, before | |
| its shell is closed). This is the only function that can veto the | |
| close, so it's a good place for an "Are you sure" kind of dialog.</td> | |
| <td><code></code></td> | |
| </tr> | |
| <tr> | |
| <td>postWindowClose</td> | |
| <td>Called after the Workbench window is closed. Can be used to clean | |
| up anything created by <code>preWindowOpen</code>.</td> | |
| <td><code></code></td> | |
| </tr> | |
| </table> | |
| <p><b>Table 6. Advanced methods in <code>WorkbenchWindowAdvisor</code>. | |
| </b></p> | |
| <table border="1"> | |
| <tr> | |
| <th>Method</th> | |
| <th>Description</th> | |
| <th>Parameter(s)</th> | |
| </tr> | |
| <tr> | |
| <td>createWindowContents</td> | |
| <td>Creates the contents of one window. Override this method to define | |
| custom contents and layout.</td> | |
| <td><code>Shell</code></td> | |
| </tr> | |
| <tr> | |
| <td>createEmptyWindowContents</td> | |
| <td>Like <code>createWindowContents</code>, but used when the window | |
| has no open pages. Override this method to show something other than | |
| the default window background.</td> | |
| <td><code>Composite</code></td> | |
| </tr> | |
| </table> | |
| <h3>ActionBar Advisor</h3> | |
| <p>In Eclipse jargon, "action bar" is a catch-all term for menus, | |
| toolbars, and status bars. The ActionBar Advisor handles creating | |
| Actions within these locations. A plug-in can also contribute actions | |
| dynamically with its plugin.xml file. See Listing 7 for the | |
| implementation provided by the plug-in wizard and Table 7 for the | |
| methods.</p> | |
| <p><img src="../images/note.gif" alt="Note: " width="62" height="13">The | |
| whole action, command and keybinding system is a bit of a mess in | |
| Eclipse 3.1. For example you can't add combo boxes to action bars, and | |
| plugin.xml can't contribute actions to the status bar. Getting key | |
| bindings to work involves multiple steps. Hopefully this will be cleaned | |
| up in a future release.</p> | |
| <p><b>Listing 7. ApplicationActionBarAdvisor.java </b></p> | |
| <tt class="java"><font class="java4">package </font><font class="java10">org.eclipse.ui.tutorials.rcp.part2;<br /> | |
| <br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.jface.action.IMenuManager;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.IWorkbenchWindow;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.application.ActionBarAdvisor;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.application.IActionBarConfigurer;<br /> | |
| <br /> | |
| </font><font class="java4">public class </font><font class="java10">ApplicationActionBarAdvisor | |
| </font><font class="java4">extends </font><font class="java10">ActionBarAdvisor | |
| </font><font class="java8">{<br /> | |
| <br /> | |
|     </font><font class="java4">public </font><font | |
| class="java10">ApplicationActionBarAdvisor</font><font class="java8">(</font><font | |
| class="java10">IActionBarConfigurer configurer</font><font | |
| class="java8">) {<br /> | |
|         </font><font class="java4">super</font><font | |
| class="java8">(</font><font class="java10">configurer</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|     </font><font class="java8">}<br /> | |
| <br /> | |
|     </font><font class="java4">protected </font><font | |
| class="java9">void </font><font class="java10">makeActions</font><font | |
| class="java8">(</font><font class="java10">IWorkbenchWindow window</font><font | |
| class="java8">) {<br /> | |
|     }<br /> | |
| <br /> | |
|     </font><font class="java4">protected </font><font | |
| class="java9">void </font><font class="java10">fillMenuBar</font><font | |
| class="java8">(</font><font class="java10">IMenuManager menuBar</font><font | |
| class="java8">) {<br /> | |
|     }<br /> | |
|     <br /> | |
| }</font></tt> | |
| <p><b>Table 7. Methods you can override in <code>ActionBarAdvisor</code>. | |
| </b></p> | |
| <table border="1"> | |
| <tr> | |
| <th>Method</th> | |
| <th>Description</th> | |
| <th>Parameter(s)</th> | |
| </tr> | |
| <tr> | |
| <td>makeActions</td> | |
| <td>Called to create the actions used in the fill methods.</td> | |
| <td><code>IWorkbenchWindow</code></td> | |
| </tr> | |
| <tr> | |
| <td>fillMenuBar</td> | |
| <td>Called to fill the menu bar with the main menus for the window.</td> | |
| <td><code>IMenuManager</code></td> | |
| </tr> | |
| <tr> | |
| <td>fillCoolBar</td> | |
| <td>Called to fill the cool bar with the main toolbars for the window.</td> | |
| <td><code>ICoolBarManager</code></td> | |
| </tr> | |
| <tr> | |
| <td>fillStatusLine</td> | |
| <td>Called to fill the status line with the main status line | |
| contributions for the window.</td> | |
| <td><code>IStatusLineManager</code></td> | |
| </tr> | |
| <tr> | |
| <td>isApplicationMenu</td> | |
| <td>Return true if the menu is one of yours. OLE specific; see Javadoc | |
| for details.</td> | |
| <td><code>String</code></td> | |
| </tr> | |
| </table> | |
| <h2>Plug-in class</h2> | |
| <p>The plug-in class is an optional singleton class that can be used to | |
| store global information for the plug-in. It's also a convenient place | |
| to put a few static utility functions used by other classes in the | |
| plug-in. See Listing 8 for the plug-in class that was created for us by | |
| the plug-in wizard.</p> | |
| <p><b>Listing 8. Part2Plugin.java </b></p> | |
| <tt class="java"><font class="java4">package </font><font class="java10">org.eclipse.ui.tutorials.rcp.part2;<br /> | |
| <br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.ui.plugin.*;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.eclipse.jface.resource.ImageDescriptor;<br /> | |
| </font><font class="java4">import </font><font class="java10">org.osgi.framework.BundleContext;<br /> | |
| <br /> | |
| </font><font class="java14">/**<br /> | |
| * The main plugin class to be used in the desktop.<br /> | |
| */<br /> | |
| </font><font class="java4">public class </font><font class="java10">Part2Plugin | |
| </font><font class="java4">extends </font><font class="java10">AbstractUIPlugin | |
| </font><font class="java8">{<br /> | |
| <br /> | |
|   </font><font class="java3">//The shared instance.<br /> | |
|   </font><font class="java4">private static </font><font | |
| class="java10">Part2Plugin plugin;<br /> | |
|   <br /> | |
|   </font><font class="java14">/**<br /> | |
|    * The constructor.<br /> | |
|    */<br /> | |
|   </font><font class="java4">public </font><font class="java10">Part2Plugin</font><font | |
| class="java8">() {<br /> | |
|     </font><font class="java10">plugin = </font><font | |
| class="java4">this</font><font class="java10">;<br /> | |
|   </font><font class="java8">}<br /> | |
| <br /> | |
|   </font><font class="java14">/**<br /> | |
|    * This method is called upon plug-in activation<br /> | |
|    */<br /> | |
|   </font><font class="java4">public </font><font class="java9">void | |
| </font><font class="java10">start</font><font class="java8">(</font><font | |
| class="java10">BundleContext context</font><font class="java8">) </font><font | |
| class="java4">throws </font><font class="java10">Exception </font><font | |
| class="java8">{<br /> | |
|     </font><font class="java4">super</font><font | |
| class="java10">.start</font><font class="java8">(</font><font | |
| class="java10">context</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|   </font><font class="java8">}<br /> | |
| <br /> | |
|   </font><font class="java14">/**<br /> | |
|    * This method is called when the plug-in is stopped<br /> | |
|    */<br /> | |
|   </font><font class="java4">public </font><font class="java9">void | |
| </font><font class="java10">stop</font><font class="java8">(</font><font | |
| class="java10">BundleContext context</font><font class="java8">) </font><font | |
| class="java4">throws </font><font class="java10">Exception </font><font | |
| class="java8">{<br /> | |
|     </font><font class="java4">super</font><font | |
| class="java10">.stop</font><font class="java8">(</font><font | |
| class="java10">context</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|     plugin = </font><font class="java4">null</font><font | |
| class="java10">;<br /> | |
|   </font><font class="java8">}<br /> | |
| <br /> | |
|   </font><font class="java14">/**<br /> | |
|    * Returns the shared instance.<br /> | |
|    */<br /> | |
|   </font><font class="java4">public static </font><font | |
| class="java10">Part2Plugin getDefault</font><font class="java8">() {<br /> | |
|     </font><font class="java4">return </font><font | |
| class="java10">plugin;<br /> | |
|   </font><font class="java8">}<br /> | |
| <br /> | |
|   </font><font class="java14">/**<br /> | |
|    * Returns an image descriptor for the image file at the | |
| given<br /> | |
|    * plug-in relative path.<br /> | |
|    *<br /> | |
|    * </font><font class="java11">@param </font><font | |
| class="java14">path the path<br /> | |
|    * </font><font class="java11">@return </font><font | |
| class="java14">the image descriptor<br /> | |
|    */<br /> | |
|   </font><font class="java4">public static </font><font | |
| class="java10">ImageDescriptor getImageDescriptor</font><font | |
| class="java8">(</font><font class="java10">String path</font><font | |
| class="java8">) {<br /> | |
|     </font><font class="java4">return </font><font | |
| class="java10">AbstractUIPlugin.imageDescriptorFromPlugin</font><font | |
| class="java8">(</font><font class="java5">"org.eclipse.ui.tutorials.rcp.part2"</font><font | |
| class="java10">, path</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|   </font><font class="java8">}<br /> | |
| }</font></tt> | |
| <h2>Build properties</h2> | |
| <p>The build.properties file (see Listing 9) will be needed when | |
| exporting the application for others to use. In particular if your | |
| application needs any resources like icons they should be listed here in | |
| the <code>bin.includes</code> section. The Plug-in Manifest editor | |
| provides a convenient interface to modify this file that is less | |
| error-prone than modifying it by hand.</p> | |
| <p><b>Listing 9. build.properties </b></p> | |
| <pre> | |
| source.. = <font class="java5">src/</font> | |
| output.. = <font class="java5">bin/</font> | |
| bin.includes = <font class="java5">plugin.xml,\ | |
| META-INF/,\ | |
| .</font> | |
| </pre> | |
| <h2>Conclusion</h2> | |
| <p>In part 2 of this tutorial, we looked at some of the API of the Rich | |
| Client Platform that allows you to develop customized native-looking | |
| client-side Java programs. The next part will delve into branding and | |
| deploying your application so others can use it. All the sample code for | |
| this part is included in the <a href="part2.zip">part2.zip archive file</a> | |
| that accompanies this document.</p> | |
| <h2>References</h2> | |
| <p><a href="../Article-RCP-1/tutorial1.html"> RCP Tutorial Part 1</a><br> | |
| <a href="../Article-RCP-3/tutorial3.html"> RCP Tutorial Part 3</a><br> | |
| <a href="http://www.eclipse.org/rcp" target="_blank"> Eclipse Rich | |
| Client Platform</a><br> | |
| <a href="http://www.eclipse.org/equinox" target="_blank">The Equinox | |
| project (OSGi in Eclipse)</a><br> | |
| <a href="../Article-Internationalization/how2I18n.html" target="_blank"> | |
| How to Internationalize your Eclipse Plug-in</a><br> | |
| <a | |
| href="http://www.eclipse.org/articles/Article-PDE-does-plugins/PDE-intro.html">PDE | |
| Does Plug-ins</a><br> | |
| <a | |
| href="http://www.eclipse.org/articles/Article-Plug-in-architecture/plugin_architecture.html">Notes | |
| on the Eclipse Plug-in Architecture</a><br> | |
| <a | |
| href="http://www.eclipse.org/articles/Article-Concurrency/jobs-api.html">On | |
| the Job: The Eclipse Jobs API</a><br> | |
| <a | |
| href="http://www.fawcette.com/javapro/2002_06/online/servlets_06_11_02/" | |
| target="_blank">Almost All Java Web Apps Need Model 2 (introduction to | |
| the Model 2 architecture)</a><br> | |
| <a | |
| href="http://www.eclipse.org/eclipse/development/java-api-evolution.html" | |
| target="_blank"> Evolving Java-based APIs</a><br> | |
| </p> | |
| <p>To discuss or report problems in this article see <a | |
| href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=104170">bug 104170</a>.</p> | |
| <p><small>IBM is trademark of International Business Machines | |
| Corporation in the United States, other countries, or both.</small></p> | |
| <p><small>Java and all Java-based trademarks and logos are trademarks or | |
| registered trademarks of Sun Microsystems, Inc. in the United States, | |
| other countries, or both.</small></p> | |
| <p><small>Microsoft and Windows are trademarks of Microsoft Corporation | |
| in the United States, other countries, or both.</small></p> | |
| <p><small>Other company, product, and service names may be trademarks or | |
| service marks of others.</small></p> | |
| </body> | |
| </html> |