| <!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> |
