| <!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 3</h1> | |
| <p class="summary">The Rich Client Platform (RCP) lets you reuse common | |
| functionality from the Eclipse IDE in your own applications. Parts 1 and | |
| 2 of this tutorial introduced you to the platform with a very simple | |
| example that did nothing but open a blank window. Part 3 discusses a | |
| more complicated example with menus, views, and other features. This | |
| part has been updated for Eclipse 3.1.2</p> | |
| <p><b>By Ed Burnette, SAS</b><br> | |
| <font size="-1">July 28, 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>The previous two parts examined a simple application that | |
| demonstrated the basic concepts of the Rich Client Platform (RCP). We | |
| used one of the plug-in project templates provided by the Eclipse SDK | |
| called "Hello RCP". Now it's time to delve a little deeper into a more | |
| complex application. We could add one thing at a time to the simple | |
| application, but in practice that's not the best way to do it.</p> | |
| <p>When you're writing these apps yourself, the quickest way is to find | |
| a template or other application that is close to the one you want to | |
| build and copy that. That's exactly what we'll do here, using a | |
| different template called "RCP Mail". By the end of this tutorial you | |
| should have the information you need to understand how this sample works | |
| so you can adapt it for your own application.</p> | |
| <h2>RCP Mail template</h2> | |
| <p>The RCP Mail template is not a functioning mail application but | |
| instead is a sample standalone RCP example provided with the Eclipse SDK | |
| that demonstrates how to:</p> | |
| <ul> | |
| <li>add top-level menus and toolbars with actions</li> | |
| <li>add keybindings to actions</li> | |
| <li>create views that can't be closed and multiple instances of the | |
| same view</li> | |
| <li>create perspectives with placeholders for new views</li> | |
| <li>use the default About dialog</li> | |
| <li>create a product definition</li> | |
| </ul> | |
| <p>As in part 1, to create the example, select <b>File > New > | |
| Project</b>, then expand <b>Plug-in Development</b> and double-click <b>Plug-in | |
| Project</b> to bring up the Plug-in Project wizard. On the subsequent | |
| pages, enter a Project name such as <b>org.eclipse.ui.tutorials.rcp.part3</b>, | |
| indicate you want a Java project, select the version of Eclipse you're | |
| targetting (at least 3.1), and enable the option to Create an OSGi | |
| bundle manifest. Then click <b>Next ></b>.</p> | |
| <p>For the option "Would you like to create a rich client application?". | |
| Select <b>Yes</b>. Leave all the other options at their default values. | |
| Click <b>Next ></b> to continue.</p> | |
| <p>Enable the option to Create a plug-in using one of the templates, | |
| then select the RCP Mail Template. Click <b>Finish</b> to accept all the | |
| defaults and generate the project (see Figure 1).</p> | |
| <p><img src="../images/note.gif" alt="Note: " width="62" height="13"> | |
| All the source code for this part can be found in the <a | |
| href="part3.zip">accompanying zip file</a>.</p> | |
| <p><img src="images/part3project_cs.png" alt=""></p> | |
| <p><b>Figure 1. The example generated by the RCP Mail Template can serve | |
| as a skeleton for your own RCP application.</b></p> | |
| <p>Test the application by clicking on "Launch an Eclipse application" | |
| from the Plug-in Manifest Editor. If it works you should see the | |
| application shown in Figure 2.</p> | |
| <p><img src="images/rcpmail_s.png" alt=""></p> | |
| <p><b>Figure 2. The RCP Mail Template can serve as a skeleton for your | |
| own RCP application. </b></p> | |
| <h2>Views</h2> | |
| <p>RCP Mail has two views, one on the left that shows all your waiting | |
| mail messages, and one on the right that examines a particular mail | |
| message. These views are defined in plugin.xml using the <code>org.eclipse.ui.views</code> | |
| extension point. Listing 1 shows the definition of the Message view.</p> | |
| <p><b>Listing 1. Message view defined in plugin.xml</b></p> | |
| <pre> | |
| <extension | |
| point="org.eclipse.ui.views"> | |
| <view | |
| name="Message" | |
| allowMultiple="true" | |
| icon="icons/sample2.gif" | |
| class="org.eclipse.ui.tutorials.rcp.part3.View" | |
| id="org.eclipse.ui.tutorials.rcp.part3.view"> | |
| </view> | |
| </extension> | |
| </pre> | |
| <p>The sample2.gif file is a 16x16 icon in GIF format used for the | |
| view's title bar. The <code>id</code> attribute is just a unique string | |
| that identifies the view. The <code>class</code> attribute specifies the | |
| fully qualified name of your View class (see below). The <code>allowMultiple</code> | |
| option lets you have more than one view of a particular type active at | |
| once. By default, Eclipse would only let you have one.</p> | |
| <p>The View class extends the abstract class <code>org.eclipse.ui.part.ViewPart</code>. | |
| A partial listing is shown in Listing 2. Only the <code>createPartControl()</code> | |
| and <code>setFocus()</code> methods need to be implemented.</p> | |
| <p><b>Listing 2. View.java</b></p> | |
| <tt class="java"><font class="java10">   </font><font | |
| class="java4">public class </font><font class="java10">View </font><font | |
| class="java4">extends </font><font class="java10">ViewPart </font><font | |
| class="java8">{<br /> | |
|   <br /> | |
| <img src="../images/tag_1.gif" height="13" width="24" align="center" | |
| alt="#1"> </font><font class="java4">public static final </font><font | |
| class="java10">String ID = </font><font class="java5">"org.eclipse.ui.tutorials.rcp.part3.view"</font><font | |
| class="java10">;<br /> | |
|     <br /> | |
| <img src="../images/tag_2.gif" height="13" width="24" align="center" | |
| alt="#2"> </font><font class="java4">public </font><font class="java9">void | |
| </font><font class="java10">createPartControl</font><font class="java8">(</font><font | |
| class="java10">Composite parent</font><font class="java8">) {<br /> | |
|       </font><font class="java10">Composite top | |
| = </font><font class="java4">new </font><font class="java10">Composite</font><font | |
| class="java8">(</font><font class="java10">parent, SWT.NONE</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|       ...etc...<br /> | |
|     </font><font class="java8">}<br /> | |
|   <br /> | |
|     </font><font class="java4">public </font><font | |
| class="java9">void </font><font class="java10">setFocus</font><font | |
| class="java8">() {<br /> | |
|     }<br /> | |
|   }</font></tt> | |
| <p>Notes:</p> | |
| <table border="0"> | |
| <tr> | |
| <td valign="baseline"><img src="../images/tag_1.gif" height="13" | |
| width="24" alt="#1"></td> | |
| <td>Defining constants that start with <code>ID_</code> is a pattern | |
| you'll see used over and over again in the Eclipse source code. Here | |
| we use it to duplicate the same id used in the plug-in manifest. This | |
| will be used later when we need a reference to the view.</td> | |
| </tr> | |
| <tr> | |
| <td valign="baseline"><img src="../images/tag_2.gif" height="13" | |
| width="24" alt="#2"></td> | |
| <td>The most important part of this class is the <code>createPartControl</code> | |
| method. This is where you will create your JFace or SWT controls that | |
| make up the view. View programming is beyond the scope of this | |
| tutorial but the reference section has some resources you can use to | |
| learn more.</td> | |
| </tr> | |
| </table> | |
| <p>You may be wondering, how does Eclipse know to put the Mailbox view | |
| on the left and the Messages view on the right? That's where the | |
| Perspective comes in.</p> | |
| <h2>Perspectives</h2> | |
| <p>Views (and editors) can only appear in the context of a <i>perspective</i>. | |
| The perspective is defined in plugin.xml with the <code>org.eclipse.ui.perspectives</code> | |
| extension. The initial layout for it (i.e., what parts it starts up | |
| with) is set up in code. Listing 3 shows the layout for the perspective | |
| in the RCP Mail application.</p> | |
| <p><b>Listing 3. Perspective.java</b></p> | |
| <tt class="java"><font class="java4">   </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 /> | |
| <img src="../images/tag_1.gif" height="13" width="24" align="center" | |
| alt="#1">   </font><font class="java10">String editorArea = | |
| layout.getEditorArea</font><font class="java8">()</font><font | |
| class="java10">;<br /> | |
|       layout.setEditorAreaVisible</font><font | |
| class="java8">(</font><font class="java4">false</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|       <br /> | |
| <img src="../images/tag_2.gif" height="13" width="24" align="center" | |
| alt="#2">   layout.addStandaloneView</font><font | |
| class="java8">(</font><font class="java10">NavigationView.ID, false, | |
| IPageLayout.LEFT, </font><font class="java7">0.25f</font><font | |
| class="java10">, editorArea</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|       <br /> | |
| <img src="../images/tag_3.gif" height="13" width="24" align="center" | |
| alt="#3">   IFolderLayout folder = layout.createFolder</font><font | |
| class="java8">(</font><font class="java5">"messages"</font><font | |
| class="java10">, IPageLayout.TOP, </font><font class="java7">0.5f</font><font | |
| class="java10">, editorArea</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|       folder.addPlaceholder</font><font | |
| class="java8">(</font><font class="java10">View.ID + </font><font | |
| class="java5">":*"</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|       folder.addView</font><font class="java8">(</font><font | |
| class="java10">View.ID</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|       <br /> | |
| <img src="../images/tag_4.gif" height="13" width="24" align="center" | |
| alt="#4">   layout.getViewLayout</font><font class="java8">(</font><font | |
| class="java10">NavigationView.ID</font><font class="java8">)</font><font | |
| class="java10">.setCloseable</font><font class="java8">(</font><font | |
| class="java4">false</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|     </font><font class="java8">}<br /> | |
|   }</font></tt> | |
| <p>Notes:</p> | |
| <table border="0"> | |
| <tr> | |
| <td valign="baseline"><img src="../images/tag_1.gif" height="13" | |
| width="24" alt="#1"></td> | |
| <td>Since this example doesn't use editors you turn off the editor | |
| area here so you won't have a big blank space in the middle of your | |
| Workbench Window. If you have editors, leave this out.</td> | |
| </tr> | |
| <tr> | |
| <td valign="baseline"><img src="../images/tag_2.gif" height="13" | |
| width="24" alt="#2"></td> | |
| <td>This line adds the Navigation view to the perspective so it will | |
| be visible by default. It's a <i>standalone</i> view meaning it can't | |
| be docked or stacked with other views, and it doesn't have a title | |
| bar. The positioning parameters say to place this view to the left of | |
| the editor area and let it take 1/4 of the horizontal space of the | |
| Workbench Window. This might be a little strange since we don't have | |
| an editor area but it's lurking around somewhere even if it's | |
| invisible.</td> | |
| </tr> | |
| <tr> | |
| <td valign="baseline"><img src="../images/tag_3.gif" height="13" | |
| width="24" alt="#3"></td> | |
| <td>Remember when the Messages view was created earlier, it used the <code>allowMultiple="true"</code> | |
| option? This means you can't give a position for "the" Messages view | |
| because there can be more than one. So first, you create a place for | |
| them all to be stacked on top of each other (a <i>folder</i>). Then | |
| you call <code>addPlaceholder()</code> to associate that folder with | |
| the pattern that will match the ids of all Message views. Finally, you | |
| call <code>addView()</code> to add one Message view for demonstration | |
| purposes. In a real application you would probably remember which | |
| messages were previously open and re-open those here when you restart | |
| the program.</td> | |
| </tr> | |
| <tr> | |
| <td valign="baseline"><img src="../images/tag_4.gif" height="13" | |
| width="24" alt="#4"></td> | |
| <td>Just for good measure, we make the Navigation view unclosable. We | |
| always want our list of mailboxes to be visible. This is covered in | |
| more detail below.</td> | |
| </tr> | |
| </table> | |
| <p><img src="../images/tip.gif" alt="Tip: " width="62" height="13"> To | |
| remember the user's layout and window sizes for the next time they start | |
| your application, add <code>configurer.setSaveAndRestore(true);</code> | |
| to the <code>initialize()</code> method of <code>WorkbenchAdvisor</code>.</p> | |
| <h3>Unclosable and unmoveable views</h3> | |
| <p>By default, views will be moveable, resizeable, and closable. Often | |
| you don't want that flexibility. For example, if you're writing an order | |
| entry application for unsophisticated users, you don't want to have to | |
| answer help desk questions about what to do if somebody accidentally | |
| closes the form view. For this reason the Eclipse platform supports the | |
| notion of <i>fixed</i> perspectives and <i>unclosable/unmoveable</i> | |
| views.</p> | |
| <p>The RCP Mail example set the Navigation view to be unclosable by | |
| using the <code>setCloseable()</code> method. A better way might be to | |
| use a fixed perspective. A fixed perspective makes all of the views it | |
| contains unclosable, plus it prevents any of them from being moved or | |
| resized. To make a perspective fixed, you could call the <code>setFixed(true)</code> | |
| method on the layout inside <code>createInitialLayout()</code>, or | |
| simply add the <code>fixed="true"</code> attribute to its definition in | |
| plugin.xml.</p> | |
| <p>By using a fixed perspective and turning off the shortcut bar, you | |
| can lock the user into one perspective and hide the concept of | |
| perspectives from them altogether.</p> | |
| <h2>Menus and Toolbars</h2> | |
| <p>Letting people configure all the menus and toolbars was one of the | |
| first, most basic requirement of the Rich Client Platform. There are two | |
| ways to add menus and toolbars in an RCP application:</p> | |
| <ul> | |
| <li>Extend the <code>ActionBarAdvisor</code> class in Java code, or</li> | |
| <li>Use the <code>org.eclipse.ui.actionSets</code> extension in the | |
| plug-in manifest</li> | |
| </ul> | |
| <p>Extending <code>ActionBarAdvisor</code> is the only way to reference | |
| built-in Workbench actions, so the example uses that technique (see | |
| Listing 4). If you're trying to use the same code in a stand-alone RCP | |
| application and a plug-in for the Eclipse IDE, the best practice is to | |
| use <code>org.eclipse.ui.actionSets</code> as much as possible.</p> | |
| <p><img src="../images/note.gif" alt="Note: " width="62" height="13"> | |
| Actions, commands, menus, and toolbars are undergoing some restructuring | |
| in Eclipse 3.2 or 3.3 so this section is likely to change. | |
| See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=36968">bug 36968</a> | |
| for more information.</p> | |
| <p><b>Listing 4. ApplicationActionBarAdvisor.java</b></p> | |
| <tt class="java"><font class="java4"> </font><font class="java14">/**<br /> | |
| * An action bar advisor is responsible for creating, adding, and | |
| disposing of the<br /> | |
| * actions added to a workbench window. Each window will be populated | |
| with<br /> | |
| * new actions.<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="java3">// Actions - important to | |
| allocate these only in makeActions, and then use them<br /> | |
|     // in the fill methods.  This ensures that the | |
| actions aren't recreated<br /> | |
|     // when fillActionBars is called with FILL_PROXY.<br /> | |
|     </font><font class="java4">private </font><font | |
| class="java10">IWorkbenchAction exitAction;<br /> | |
|     </font><font class="java4">private </font><font | |
| class="java10">IWorkbenchAction aboutAction;<br /> | |
|     </font><font class="java4">private </font><font | |
| class="java10">IWorkbenchAction newWindowAction;<br /> | |
|     </font><font class="java4">private </font><font | |
| class="java10">OpenViewAction openViewAction;<br /> | |
|     </font><font class="java4">private </font><font | |
| class="java10">Action messagePopupAction;<br /> | |
|     <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 /> | |
| <img src="../images/tag_1.gif" height="13" width="24" align="center" | |
| alt="#1"> </font><font class="java4">protected </font><font | |
| class="java9">void </font><font class="java10">makeActions</font><font | |
| class="java8">(</font><font class="java4">final </font><font | |
| class="java10">IWorkbenchWindow window</font><font class="java8">) {<br /> | |
|         </font><font class="java3">// | |
| Creates the actions and registers them.<br /> | |
|         // Registering is needed to | |
| ensure that key bindings work.<br /> | |
|         // The corresponding commands | |
| keybindings are defined in the plugin.xml file.<br /> | |
|         // Registering also provides | |
| automatic disposal of the actions when<br /> | |
|         // the window is closed.<br /> | |
| <br /> | |
|         </font><font class="java10">exitAction | |
| = ActionFactory.QUIT.create</font><font class="java8">(</font><font | |
| class="java10">window</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|         register</font><font | |
| class="java8">(</font><font class="java10">exitAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         <br /> | |
|         aboutAction = | |
| ActionFactory.ABOUT.create</font><font class="java8">(</font><font | |
| class="java10">window</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|         register</font><font | |
| class="java8">(</font><font class="java10">aboutAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         <br /> | |
|         newWindowAction = | |
| ActionFactory.OPEN_NEW_WINDOW.create</font><font class="java8">(</font><font | |
| class="java10">window</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|         register</font><font | |
| class="java8">(</font><font class="java10">newWindowAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         <br /> | |
|         openViewAction = </font><font | |
| class="java4">new </font><font class="java10">OpenViewAction</font><font | |
| class="java8">(</font><font class="java10">window, </font><font | |
| class="java5">"Open Another Message View"</font><font | |
| class="java10">, View.ID</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|         register</font><font | |
| class="java8">(</font><font class="java10">openViewAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         <br /> | |
|         messagePopupAction = </font><font | |
| class="java4">new </font><font class="java10">MessagePopupAction</font><font | |
| class="java8">(</font><font class="java5">"Open Message"</font><font | |
| class="java10">, window</font><font class="java8">)</font><font | |
| class="java10">;<br /> | |
|         register</font><font | |
| class="java8">(</font><font class="java10">messagePopupAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|     </font><font class="java8">}<br /> | |
|     <br /> | |
| <img src="../images/tag_2.gif" height="13" width="24" align="center" | |
| alt="#2"> </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 /> | |
|         </font><font class="java10">MenuManager | |
| fileMenu = </font><font class="java4">new </font><font class="java10">MenuManager</font><font | |
| class="java8">(</font><font class="java5">"&File"</font><font | |
| class="java10">, IWorkbenchActionConstants.M_FILE</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         MenuManager helpMenu = </font><font | |
| class="java4">new </font><font class="java10">MenuManager</font><font | |
| class="java8">(</font><font class="java5">"&Help"</font><font | |
| class="java10">, IWorkbenchActionConstants.M_HELP</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         <br /> | |
|         menuBar.add</font><font | |
| class="java8">(</font><font class="java10">fileMenu</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         </font><font class="java3">// | |
| Add a group marker indicating where action set menus will appear.<br /> | |
|         </font><font class="java10">menuBar.add</font><font | |
| class="java8">(</font><font class="java4">new </font><font | |
| class="java10">GroupMarker</font><font class="java8">(</font><font | |
| class="java10">IWorkbenchActionConstants.MB_ADDITIONS</font><font | |
| class="java8">))</font><font class="java10">;<br /> | |
|         menuBar.add</font><font | |
| class="java8">(</font><font class="java10">helpMenu</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         <br /> | |
|         </font><font class="java3">// | |
| File<br /> | |
|         </font><font class="java10">fileMenu.add</font><font | |
| class="java8">(</font><font class="java10">newWindowAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         fileMenu.add</font><font | |
| class="java8">(</font><font class="java4">new </font><font | |
| class="java10">Separator</font><font class="java8">())</font><font | |
| class="java10">;<br /> | |
|         fileMenu.add</font><font | |
| class="java8">(</font><font class="java10">messagePopupAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         fileMenu.add</font><font | |
| class="java8">(</font><font class="java10">openViewAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         fileMenu.add</font><font | |
| class="java8">(</font><font class="java4">new </font><font | |
| class="java10">Separator</font><font class="java8">())</font><font | |
| class="java10">;<br /> | |
|         fileMenu.add</font><font | |
| class="java8">(</font><font class="java10">exitAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         <br /> | |
|         </font><font class="java3">// | |
| Help<br /> | |
|         </font><font class="java10">helpMenu.add</font><font | |
| class="java8">(</font><font class="java10">aboutAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|     </font><font class="java8">}<br /> | |
|     <br /> | |
| <img src="../images/tag_3.gif" height="13" width="24" align="center" | |
| alt="#3"> </font><font class="java4">protected </font><font | |
| class="java9">void </font><font class="java10">fillCoolBar</font><font | |
| class="java8">(</font><font class="java10">ICoolBarManager coolBar</font><font | |
| class="java8">) {<br /> | |
|         </font><font class="java10">IToolBarManager | |
| toolbar = </font><font class="java4">new </font><font class="java10">ToolBarManager</font><font | |
| class="java8">(</font><font class="java10">SWT.FLAT | SWT.RIGHT</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         coolBar.add</font><font | |
| class="java8">(</font><font class="java4">new </font><font | |
| class="java10">ToolBarContributionItem</font><font class="java8">(</font><font | |
| class="java10">toolbar, </font><font class="java5">"main"</font><font | |
| class="java8">))</font><font class="java10">;   <br /> | |
|         toolbar.add</font><font | |
| class="java8">(</font><font class="java10">openViewAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|         toolbar.add</font><font | |
| class="java8">(</font><font class="java10">messagePopupAction</font><font | |
| class="java8">)</font><font class="java10">;<br /> | |
|     </font><font class="java8">}<br /> | |
| }</font></tt> | |
| <p>Notes:</p> | |
| <table border="0"> | |
| <tr> | |
| <td valign="baseline"><img src="../images/tag_1.gif" height="13" | |
| width="24" alt="#1"></td> | |
| <td><code>makeActions()</code> is called by the Platform to create all | |
| the <i>actions</i> that will be referenced in the menus and toolbars. | |
| An action is a simple object that has a user interface component | |
| (i.e., the way it appears in a menu or toolbar) and a functionality | |
| component (i.e., what it does). A list of supported Workbench actions | |
| can be found by looking at the Javadoc for <code>ActionFactory</code> | |
| and <code>ContributionItemFactory</code>.</td> | |
| </tr> | |
| <tr> | |
| <td valign="baseline"><img src="../images/tag_2.gif" height="13" | |
| width="24" alt="#2"></td> | |
| <td><code>fillMenuBar()</code> is called to populate the Workbench's | |
| menu bar with whatever actions you would like to have appear there. | |
| The RCP Mail example has two top level menus, "File" and "Help". First | |
| you create a MenuManager for each of the top level menus. Then you add | |
| the menus to the menu bar, and the actions to the menus. See the | |
| references section for more information about defining views and | |
| menus.</td> | |
| </tr> | |
| <tr> | |
| <td valign="baseline"><img src="../images/tag_3.gif" height="13" | |
| width="24" alt="#3"></td> | |
| <td><code>fillCoolBar()</code> defines the main coolbar for the | |
| Workbench. A <i>coolbar</i> is a collection of toolbars, and a <i>toolbar</i> | |
| is a collection of actions. In this example there is only one toolbar. | |
| You create a new toolbar manager to hold it, add the toolbar to the | |
| coolbar, and then add the actions to the toolbar.</td> | |
| </tr> | |
| </table> | |
| <p><img src="../images/note.gif" alt="Note: " width="62" height="13"> | |
| It's always a good idea to create some placeholders (like <code>MB_ADDITIONS</code>) | |
| where additional menu items can be added by plug-ins. There are a number | |
| of standard placeholder names for menus and toolbars that you should use | |
| when trying to make yours work just like the ones in the IDE. By using | |
| these predefined groups, plug-ins that contribute menu and toolbar items | |
| to the Eclipse IDE can also contribute them to your RCP application. | |
| These aren't documented anywhere other than in the Javadoc for <code>IWorkbenchActionConstants</code>, | |
| and even there you won't find any guidance for their intended order. The | |
| best reference is the source code for the Eclipse IDE itself.</p> | |
| <h2>Making it a product</h2> | |
| <p>The RCP Mail template already defines a product using the <code>org.eclipse.core.runtime.products</code> | |
| extension. However it doesn't come with a <code>.products</code> file so | |
| you'll need to make one for full branding and customization. Right click | |
| on the project and select <b>New > Product Configuration</b>. Select | |
| the existing product ID (<code>org.eclipse.ui.tutorials.rcp.part3.product</code>) | |
| and the existing application (<code>org.eclipse.ui.tutorials.rcp.part3.application</code>) | |
| from the dropdown lists. Then provide a Product Name such as <b>RCP | |
| Tutorial 3</b>. Finally, switch to the Configuration tab and add the | |
| plug-ins just like you did in part 1. Save your work and test out | |
| launching the product to make sure it still works that way.</p> | |
| <h2>Branding</h2> | |
| <p>While the application is still running, select <b>Help > About RCP | |
| Tutorial 3</b>. You should get a generic dialog that looks like Figure | |
| 3.</p> | |
| <p><img src="images/about1_s.png" alt=""></p> | |
| <p><b>Figure 3. The standard About box looks like this before branding | |
| is applied.</b></p> | |
| <p>Let's spruce that up a little to demonstrate RCP's branding options. | |
| Exit the sample application and switch to the Branding tab of the | |
| Product Configuration editor. Find the section that has options for the | |
| About Dialog. Next to the Image option click on the Browse button and | |
| select <b>product_lg.gif</b> in the plug-in project. This file was put | |
| there by the RCP Mail template, but you could easily supply your own. | |
| Click OK to continue.</p> | |
| <p>Now click in the Text section and type in whatever you want your | |
| About box to say, such as the name of your product, the version number, | |
| instructions for getting support, and any necessary copyright and | |
| licensing information. When you're done, save the configuration, go back | |
| to the Overview tab, click Synchronize, and Launch again. When the | |
| application comes up, bring up the About box and you'll see something | |
| like Figure 4.</p> | |
| <p><img src="images/about2_s.png" alt=""></p> | |
| <p><b>Figure 4. With a branding you can add those little touches that | |
| make the application your own.</b></p> | |
| <p><img src="../images/tip.gif" alt="Tip: " width="62" height="13"> Be | |
| sure to include any "extra" files like images and icons in your | |
| plug-in's Build Configuration (the Build tab in the Plug-in Manifest | |
| editor, or the <code>build.properties</code> file). Otherwise they won't | |
| make it into the plug-in's jar file or be copied during an Export | |
| operation. The template we used already took care of that, but it's easy | |
| to forget in your own applications.</p> | |
| <h2>Conclusion</h2> | |
| <p>Congratulations! If you made it this far, you are well on your way to | |
| developing your own Rich Client Platform applications. In this part of | |
| the tutorial, we picked apart the RCP Mail template to see how it works. | |
| Now you can use it as a starting point for your own projects instead of | |
| beginning from scratch. Take a look at the references below for more | |
| information and community sites where you can discuss RCP with other | |
| developers who are using it. All the source code for this part can be | |
| found in the <a href="part3.zip">accompanying zip file</a>.</p> | |
| <h2>References</h2> | |
| <p><a href="../Article-RCP-1/tutorial1.html">RCP Tutorial Part 1</a><br> | |
| <a href="../Article-RCP-2/tutorial2.html">RCP Tutorial Part 2</a><br> | |
| <a href="http://www.eclipse.org/rcp" target="_blank">Eclipse Rich Client | |
| Platform</a><br> | |
| <a href="../viewArticle/ViewArticle2.html">Creating an Eclipse View</a><br> | |
| <a href="../Online%20Help/help1.htm">Contributing a Little Help</a><br> | |
| </p> | |
| <p>To discuss or report problems in this article see <a | |
| href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=104171">bug 104171</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> |