bundles/org.eclipse.ui.tutorials.rcp.part3/html/tutorial3.html - platform/eclipse.platform.ui - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>

 <head>
 <title>Rich Client Platform</title>
 <link href="default_style.css" rel=stylesheet>
 </head>

 <body>

 <div align="right">
   <font face="Times New Roman, Times, serif" size="2">Copyright © 2004 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"></h1>
 </div>
 <h1 align="center">Rich Client Tutorial Part 3</h1>
 <p class="summary">
 The Rich Client Platform (RCP)
 lets you pick and choose functionality from Eclipse
 for use in your own applications.
 Parts 1 and 2 of this tutorial introduced you to the platform
 and some of the configuration classes it provides.
 Part 3 discusses how to add
 functionality such as menus, views, and help files.
 </p>
 <p><b>By Ed Burnette, SAS</b><br>
 <font size="-1">July 28, 2004</font></p>
 <hr width="100%">

 <h2>Introduction</h2>
 <p>
 Much of our discussion in the previous
 two parts focused on taking things away from
 the platform - turning off toolbars, getting
 rid of menus, and so forth.
 For this installment we're going to look at putting things back in.
 All source code for the tutorial
 can be downloaded from the
 <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ui.tutorials.rcp.part3">Eclipse project here</a>.
 </p>

 <h2>Views</h2>
 <p>
 Let's start with a view.
 Eclipse's Plug-in Development Environment
 provides a nice set of extension templates to get you started writing
 sample views, editors, menus,
 and other components.
 Unfortunately, as of this writing, they are almost useless for
 RCP development because the code produced introduces all
 sorts of dependencies on IDE and resource packages
 and plug-ins.
 </p>
 <p>
 <img src="images/tip.gif" alt="Tip: " width="62" height="13">
 The rule of thumb is that anything that references a resource is
 not intended for RCP developers because of the extra code
 and dependencies on workspaces it
 pulls in.
 So if you see the <code>org.eclipse.core.resources</code>
 plug-in in your dependency list, or see an import for
 some class from that package, you're probably doing something wrong.
 This is not a hard and fast rule though, so
 resources should be considered an <i>optional</i>
 part of the Rich Client Platform.
 </p>
 <p>
 To create a view without the templates, you can
 use the schema-based extension wizards from the
 Plug-in Manifest editor (Extensions pane > Add > Generic Wizards > Schema-based
 Extensions) or simply edit the XML in the Source pane.
 Either way, you want to end up with extension XML like this:
 </p>
 <pre>
 	&lt;extension
 	      point="org.eclipse.ui.views"&gt;
 	   &lt;category
 	         name="SampleCategory"
 <img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">	         id="org.eclipse.ui.tutorials.rcp.part3.viewCategory"&gt;
 	   &lt;/category&gt;
 	   &lt;view
 	         name="Sample"
 	         icon="icons/sample.gif"
 	         category="org.eclipse.ui.tutorials.rcp.part3.viewCategory"
 <img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">	         class="org.eclipse.ui.tutorials.rcp.part3.views.SampleView"
 	         id="org.eclipse.ui.tutorials.rcp.part3.views.SampleView"&gt;
 	   &lt;/view&gt;
 	&lt;/extension&gt;
 </pre>
 <p>
 The view category (<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">)
 is a way to organize your views in the
 Show Views dialog.
 The class (<img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">)
 extends the <code>ViewPart</code> abstract class as shown below:
 </p>

 <pre>
 	public class SampleView extends ViewPart {
 <img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">	    public static final String ID_VIEW =
 	        "org.eclipse.ui.tutorials.rcp.part3.views.SampleView"; //$NON-NLS-1$

 	    private TableViewer viewer;

 	    public SampleView() {
 	    }

 <img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">	    public void createPartControl(Composite parent) {
 	        viewer =
 	            new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL | SWT.V_SCROLL);
 	        viewer.setContentProvider(new ViewContentProvider());
 	        viewer.setLabelProvider(new ViewLabelProvider());
 	        viewer.setInput(this);
 	    }

 	    public void setFocus() {
 	        viewer.getControl().setFocus();
 	    }
 	}
 </pre>
 <p>
 Defining constants that start with <code>ID_</code>
 (<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">)
 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.
 </p>
 <p>
 The most important part of this class is the <code>createPartControl</code> method
 (<img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">).
 It's where you create your JFace or SWT controls that make
 up the view.
 The rest of the source was can be found in the example project.
 View programming is beyond the scope of this tutorial
 but you can see the reference section for more information.
 </p>

 <h2>Perspective additions</h2>
 <p>
 If you run the code now you won't actually see anything different.
 Why? Because your new view can't appear unless it is added
 to the current perspective.
 You can do this through code or though the org.eclipse.ui.perspectiveExtensions
 extension.
 We'll choose the former because it's a little more flexible.
 To do this, go back to the <code>RcpPerspective</code> class
 defined earlier and modify it to look like this:
 </p>

 <pre>
 	public class RcpPerspective implements IPerspectiveFactory {
 <img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">	    public static final String ID_PERSPECTIVE =
 	        "org.eclipse.ui.tutorials.rcp.part3.RcpPerspective"; //$NON-NLS-1$

 	    public RcpPerspective() {
 	    }

 	    public void createInitialLayout(IPageLayout layout) {
 <img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">	        layout.setEditorAreaVisible(false);
 <img src="images/tag_3.gif" height="13" width="24" align="center" alt="#3">	        layout.addView(
 	            SampleView.ID_VIEW,
 	            IPageLayout.TOP,
 	            IPageLayout.RATIO_MAX,
 	            IPageLayout.ID_EDITOR_AREA);
 <img src="images/tag_4.gif" height="13" width="24" align="center" alt="#4">	        layout.addPerspectiveShortcut(ID_PERSPECTIVE);
 <img src="images/tag_5.gif" height="13" width="24" align="center" alt="#5">	        layout.addShowViewShortcut(SampleView.ID_VIEW);
 	    }
 	}
 </pre>
 <p>
 Notes:
 </p>
 <table border="0">
 <tr valign="top"><td><img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">
 <td>Again, just get in the habit of
 defining a constant for all strings, especially ids.
 <tr valign="top"><td><img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">
 <td>The Platform supports editors but we're not using
 one for this example. Therefore you need to turn off the
 editor area so you won't have a big blank space in the middle
 of your Workbench Window.
 <tr valign="top"><td><img src="images/tag_3.gif" height="13" width="24" align="center" alt="#3">
 <td>This is the most important part of the class.
 It adds the view to the perspective so it will be visible by default.
 The positioning parameters say to place this view above the
 editor area and let it take 100% 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.
 As you add more than one view to your application you can
 define the default stacking and layout of your views here.
 <tr valign="top"><td><img src="images/tag_4.gif" height="13" width="24" align="center" alt="#4">
 <td>This method causes the perspective to be
 on the short list if you implement the <code>PERSPECTIVES_SHORTLIST</code>
 menu item (see the sample code for an example).
 Without it, the perspective will only be on the long list seen
 when the user selects Window > Open Perspective > Other (or whatever
 the equivalent menu path is in your application).
 <tr valign="top"><td><img src="images/tag_5.gif" height="13" width="24" align="center" alt="#5">
 <td>Same thing, only for views.
 </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>.
 An example of this can be found in the sample project.
 </p>

 <h3>Fixed 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 Eclipse 3.0 introduces the notion of fixed
 perspectives and fixed views.
 </p>
 <p>
 A fixed view is a view that cannot be closed.
 The title bar of the view doesn't even have a close button.
 To create one of these you can use the <code>setFixed()</code>
 method on <code>IPageLayout</code>.
 </p>
 <p>
 A better way might be to use a fixed perspective.
 A fixed perspective makes all of the views it contains fixed,
 plus it prevents any of them from being moved or resized.
 To make a perspective fixed, simply add the <code>fixed="true"</code>
 attribute to its definition,
 for example:
 </p>
 <pre>
     &lt;extension
         point=&quot;org.eclipse.ui.perspectives&quot;&gt;
         &lt;perspective
             name=&quot;%perspectiveName&quot;
             icon=&quot;icons/sample.gif&quot;
             <b>fixed=&quot;true&quot;</b>
             class=&quot;org.eclipse.ui.tutorials.rcp.part3.RcpPerspective&quot;
             id=&quot;org.eclipse.ui.tutorials.rcp.part3.RcpPerspective&quot;&gt;
         &lt;/perspective&gt;
     &lt;/extension&gt;
 </pre>
 <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</h2>
 <p>
 Letting you configure all the menus was one of the first
 requirements of the RCP.
 There are two ways to add menus in an RCP application:
 </p>
 <ul>
 <li><code>WorkbenchAdvisor.fillActionBars</code>
 <li><code>org.eclipse.ui.actionSets</code> in the plug-in manifest
 </ul>
 <p>
 <code>fillActionBars</code> is the only way to reference built-in
 Workbench actions, so we'll use it for that purpose.
 Everything else can be contributed by the <code>actionSets</code> extension point.
 Both methods will be demonstrated here.
 Although the example application does not use
 toolbars, they are very similar to menus.
 </p>
 <p>
 First let's take a look at <code>fillActionBars</code>:
 </p>
 <pre>
 	public void fillActionBars(
 	    IWorkbenchWindow window,
 	    IActionBarConfigurer configurer,
 	    int flags) {
 	    super.fillActionBars(window, configurer, flags);
 <img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">         if ((flags & FILL_MENU_BAR) != 0) {
 	        fillMenuBar(window, configurer);
 	    }
 	}
 </pre>
 <p>
 <code>fillActionBars</code> is takes a flags parameter
 (<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">)
 that indicates what
 the code should really do.
 There are flag bits for filling in the menu bar, the tool bar,
 the status line, and even a bit for whether or not this is a fake
 request for preference dialogs (<code>FILL_PROXY</code>).
 The author has had some bad experiences with flags like this,
 so the example code just calls a helper function called <code>fillMenuBar</code>
 to do the actual filling.
 Here's the code for <code>fillMenuBar</code>:
 </p>
 <pre>
 	private void fillMenuBar(
 	    IWorkbenchWindow window,
 	    IActionBarConfigurer configurer) {
 	    IMenuManager menuBar = configurer.getMenuManager();
 	    menuBar.add(createFileMenu(window));
 	    menuBar.add(createEditMenu(window));
 	    menuBar.add(createWindowMenu(window));
 	    menuBar.add(createHelpMenu(window));
 	}
 </pre>
 <p>
 For this example we want to create four top-level
 menus: File, Edit, Window, and Help.
 These correspond to the menus of the same name
 in the Eclipse IDE.
 For a real application you may not want all these,
 or you might want to call them something different.
 See figure 1 for an example.
 </p>

 <img src="images/complete.png">
 <p><b>Figure 1. The Workbench menu bar is defined
 in the <code>fillActionBars</code> method of <code>WorkbenchAdvisor</code>,
 and then added to by the manifests of
 all plug-ins that extend <code>org.eclipse.ui.actionSets</code>.
 </b></p>

 <p>
 The code for all these methods can be found in the example project.
 Let's just take a closer look at one of of them, the File menu:
 </p>

 <pre>
 	private MenuManager createFileMenu(IWorkbenchWindow window) {
 <img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">	    MenuManager menu = new MenuManager(Messages.getString("File"), //$NON-NLS-1$
 	        IWorkbenchActionConstants.M_FILE);
 <img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">	    menu.add(new GroupMarker(IWorkbenchActionConstants.FILE_START));
 	    menu.add(new GroupMarker(IWorkbenchActionConstants.MB_ADDITIONS));
 <img src="images/tag_3.gif" height="13" width="24" align="center" alt="#3">	    menu.add(ActionFactory.QUIT.create(window));
 	    menu.add(new GroupMarker(IWorkbenchActionConstants.FILE_END));
 	    return menu;
 	}
 </pre>
 <p>
 All these menus work the same way.
 First you create a MenuManager for the menu
 (<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">)
 using the message file to lookup the actual human-readable title.
 Then you add all the menu items and return the manager.
 See the references section for more information about defining views and menus.
 Next, you create some placeholders
 (<img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">)
 where additional
 menu items can be added by plug-ins,
 and one real action supplied by the Workbench: the Quit action
 (<img src="images/tag_3.gif" height="13" width="24" align="center" alt="#3">).
 A list of supported Workbench actions can be found by
 looking at the Javadoc for <code>ActionFactory</code> and
 <code>ContributionItemFactory</code>.
 </p>
 <p>
 <img src="images/note.gif" alt="Note: " width="62" height="13">
 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 sample code that accompanies this tutorial was created by looking at the
 <code>IDEWorkbenchAdvisor</code> class used by the Eclipse IDE.
 </p>

 <h2>Help</h2>
 <p>
 One of the coolest features of the RCP is its help system.
 Simply by providing the table of contents in
 XML format and the documents in HTML,
 you can give your users a searchable help
 system with no coding on your part.
 First, you add an extension to your plug-in manifest like this:
 </p>
 <pre>
 	&lt;extension
 	      point="org.eclipse.help.toc"&gt;
 	   &lt;toc
 	         file="book.xml"
 	         primary="true"&gt;
 	   &lt;/toc&gt;
 	&lt;/extension&gt;
 </pre>

 <p>
 Then you create a table of contents file (book.xml in this example)
 to define a hierarchy of help topics.
 Not all the topics have to be in the contents but it is
 good practice to do so.
 Here's an example you can use to get started:
 </p>
 <pre>
 	&lt;toc label="RCP Help Sample"  topic="html/book.html"&gt;
 	   &lt;topic label="Overview" href="html/overview.html"/&gt;
 	&lt;/toc&gt;
 </pre>
 <p>
 See the references section for more information on writing
 and organizing help files, including internationalization.
 </p>
 <p>
 When you're debugging or deploying an RCP application
 that includes help you'll need to include
 several more help related plug-ins
 in addition to those listed in part 1 of the tutorial.
 Here's the current list (subject to change in future versions):
 </p>
 <ul>
 <li><code>org.apache.ant</code>
 <li><code>org.apache.lucene</code>
 <li><code>org.eclipse.help.appserver</code>
 <li><code>org.eclipse.help.base</code>
 <li><code>org.eclipse.help.ui</code>
 <li><code>org.eclipse.help.webapp</code>
 <li><code>org.eclipse.tomcat</code>
 </ul>
 <p>
 See <code>createHelpMenu()</code> in the example for code
 to add the Help Contents action to your Help menu.
 When you select it, this action will fire up a
 help browser like the one shown in figure 2.
 </p>

 <img src="images/help.png">
 <p><b>Figure 2. The Rich Client Platform provides a
 full featured online help framework so you don't have to.
 All you do is provide the content.
 </b></p>

 <h2>Build.properties</h2>
 <p>
 As you add more resources to your plug-in such as html files,
 icons, the help table of contents, and so forth,
 don't forget to update your build.properties file to
 include all the files and/or directories that need to be
 available to the plug-in at run time.
 Here is the updated build.properties XML file containing everything
 needed for the example in this section:
 </p>
 <pre>
 bin.includes = plugin.xml,\
                *.jar,\
                part3.jar,\
                plugin.properties,\
                <b>book.xml,\</b>
                <b>html/,\</b>
                <b>icons/</b>
 source.part3.jar = src/
 </pre>

 <h2>Conclusion</h2>
 <p>
 In this part of the tutorial, we
 added a simple view, some menus, and help files
 to a create a sample RCP application.
 Hopefully you can can use this example as a reference in
 your own projects.
 All the sample code for this part may be viewed at the
 <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ui.tutorials.rcp.part3">Eclipse project here</a>.
 You can use
 <a href="http://dev.eclipse.org/cvshowto.html">Eclipse's built-in CVS client</a>
 to download the source to your workspace.
 </p>
 <p>
 Congratulations!
 If you made it this far, you are
 well on your way to developing your own
 Rich Client Platform applications.
 Take a look at the references below for more information
 and community sites and mailing lists where
 you can meet other people using RCP.
 </p>

 <h2>References</h2>
 <p>
 <a href="http://eclipse.org/articles/Article-RCP-1/tutorial1.html">
 RCP Tutorial Part 1</a><br>
 <a href="http://eclipse.org/articles/Article-RCP-2/tutorial2.html">
 RCP Tutorial Part 2</a><br>
 <a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-ui-home/rcp/index.html">
 Eclipse Rich Client Platform</a><br>
 <a href="http://www.eclipse.org/articles/viewArticle/ViewArticle2.html">
 Creating an Eclipse View</a><br>
 <a href="http://www.eclipse.org/articles/Article-Online%20Help%20for%202_0/help1.htm">
 Contributing a Little Help</a><br>
 <a href="http://www.eclipsepowered.org">
 Eclipse Powered (rich client plug-ins and resources)</a><br>
 </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>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>

	<head>
	<title>Rich Client Platform</title>
	<link href="default_style.css" rel=stylesheet>
	</head>

	<body>

	<div align="right">
	<font face="Times New Roman, Times, serif" size="2">Copyright © 2004 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"></h1>
	</div>
	<h1 align="center">Rich Client Tutorial Part 3</h1>
	<p class="summary">
	The Rich Client Platform (RCP)
	lets you pick and choose functionality from Eclipse
	for use in your own applications.
	Parts 1 and 2 of this tutorial introduced you to the platform
	and some of the configuration classes it provides.
	Part 3 discusses how to add
	functionality such as menus, views, and help files.
	</p>
	<p><b>By Ed Burnette, SAS</b><br>
	<font size="-1">July 28, 2004</font></p>
	<hr width="100%">

	<h2>Introduction</h2>
	<p>
	Much of our discussion in the previous
	two parts focused on taking things away from
	the platform - turning off toolbars, getting
	rid of menus, and so forth.
	For this installment we're going to look at putting things back in.
	All source code for the tutorial
	can be downloaded from the
	<a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ui.tutorials.rcp.part3">Eclipse project here</a>.
	</p>

	<h2>Views</h2>
	<p>
	Let's start with a view.
	Eclipse's Plug-in Development Environment
	provides a nice set of extension templates to get you started writing
	sample views, editors, menus,
	and other components.
	Unfortunately, as of this writing, they are almost useless for
	RCP development because the code produced introduces all
	sorts of dependencies on IDE and resource packages
	and plug-ins.
	</p>
	<p>
	<img src="images/tip.gif" alt="Tip: " width="62" height="13">
	The rule of thumb is that anything that references a resource is
	not intended for RCP developers because of the extra code
	and dependencies on workspaces it
	pulls in.
	So if you see the <code>org.eclipse.core.resources</code>
	plug-in in your dependency list, or see an import for
	some class from that package, you're probably doing something wrong.
	This is not a hard and fast rule though, so
	resources should be considered an <i>optional</i>
	part of the Rich Client Platform.
	</p>
	<p>
	To create a view without the templates, you can
	use the schema-based extension wizards from the
	Plug-in Manifest editor (Extensions pane > Add > Generic Wizards > Schema-based
	Extensions) or simply edit the XML in the Source pane.
	Either way, you want to end up with extension XML like this:
	</p>
	<pre>
	<extension
	point="org.eclipse.ui.views">
	<category
	name="SampleCategory"
	<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1"> id="org.eclipse.ui.tutorials.rcp.part3.viewCategory">
	</category>
	<view
	name="Sample"
	icon="icons/sample.gif"
	category="org.eclipse.ui.tutorials.rcp.part3.viewCategory"
	<img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2"> class="org.eclipse.ui.tutorials.rcp.part3.views.SampleView"
	id="org.eclipse.ui.tutorials.rcp.part3.views.SampleView">
	</view>
	</extension>
	</pre>
	<p>
	The view category (<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">)
	is a way to organize your views in the
	Show Views dialog.
	The class (<img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">)
	extends the <code>ViewPart</code> abstract class as shown below:
	</p>

	<pre>
	public class SampleView extends ViewPart {
	<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1"> public static final String ID_VIEW =
	"org.eclipse.ui.tutorials.rcp.part3.views.SampleView"; //$NON-NLS-1$

	private TableViewer viewer;

	public SampleView() {
	}

	<img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2"> public void createPartControl(Composite parent) {
	viewer =
	new TableViewer(parent, SWT.MULTI \| SWT.H_SCROLL \| SWT.V_SCROLL);
	viewer.setContentProvider(new ViewContentProvider());
	viewer.setLabelProvider(new ViewLabelProvider());
	viewer.setInput(this);
	}

	public void setFocus() {
	viewer.getControl().setFocus();
	}
	}
	</pre>
	<p>
	Defining constants that start with <code>ID_</code>
	(<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">)
	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.
	</p>
	<p>
	The most important part of this class is the <code>createPartControl</code> method
	(<img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">).
	It's where you create your JFace or SWT controls that make
	up the view.
	The rest of the source was can be found in the example project.
	View programming is beyond the scope of this tutorial
	but you can see the reference section for more information.
	</p>

	<h2>Perspective additions</h2>
	<p>
	If you run the code now you won't actually see anything different.
	Why? Because your new view can't appear unless it is added
	to the current perspective.
	You can do this through code or though the org.eclipse.ui.perspectiveExtensions
	extension.
	We'll choose the former because it's a little more flexible.
	To do this, go back to the <code>RcpPerspective</code> class
	defined earlier and modify it to look like this:
	</p>

	<pre>
	public class RcpPerspective implements IPerspectiveFactory {
	<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1"> public static final String ID_PERSPECTIVE =
	"org.eclipse.ui.tutorials.rcp.part3.RcpPerspective"; //$NON-NLS-1$

	public RcpPerspective() {
	}

	public void createInitialLayout(IPageLayout layout) {
	<img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2"> layout.setEditorAreaVisible(false);
	<img src="images/tag_3.gif" height="13" width="24" align="center" alt="#3"> layout.addView(
	SampleView.ID_VIEW,
	IPageLayout.TOP,
	IPageLayout.RATIO_MAX,
	IPageLayout.ID_EDITOR_AREA);
	<img src="images/tag_4.gif" height="13" width="24" align="center" alt="#4"> layout.addPerspectiveShortcut(ID_PERSPECTIVE);
	<img src="images/tag_5.gif" height="13" width="24" align="center" alt="#5"> layout.addShowViewShortcut(SampleView.ID_VIEW);
	}
	}
	</pre>
	<p>
	Notes:
	</p>
	<table border="0">
	<tr valign="top"><td><img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">
	<td>Again, just get in the habit of
	defining a constant for all strings, especially ids.
	<tr valign="top"><td><img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">
	<td>The Platform supports editors but we're not using
	one for this example. Therefore you need to turn off the
	editor area so you won't have a big blank space in the middle
	of your Workbench Window.
	<tr valign="top"><td><img src="images/tag_3.gif" height="13" width="24" align="center" alt="#3">
	<td>This is the most important part of the class.
	It adds the view to the perspective so it will be visible by default.
	The positioning parameters say to place this view above the
	editor area and let it take 100% 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.
	As you add more than one view to your application you can
	define the default stacking and layout of your views here.
	<tr valign="top"><td><img src="images/tag_4.gif" height="13" width="24" align="center" alt="#4">
	<td>This method causes the perspective to be
	on the short list if you implement the <code>PERSPECTIVES_SHORTLIST</code>
	menu item (see the sample code for an example).
	Without it, the perspective will only be on the long list seen
	when the user selects Window > Open Perspective > Other (or whatever
	the equivalent menu path is in your application).
	<tr valign="top"><td><img src="images/tag_5.gif" height="13" width="24" align="center" alt="#5">
	<td>Same thing, only for views.
	</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>.
	An example of this can be found in the sample project.
	</p>

	<h3>Fixed 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 Eclipse 3.0 introduces the notion of fixed
	perspectives and fixed views.
	</p>
	<p>
	A fixed view is a view that cannot be closed.
	The title bar of the view doesn't even have a close button.
	To create one of these you can use the <code>setFixed()</code>
	method on <code>IPageLayout</code>.
	</p>
	<p>
	A better way might be to use a fixed perspective.
	A fixed perspective makes all of the views it contains fixed,
	plus it prevents any of them from being moved or resized.
	To make a perspective fixed, simply add the <code>fixed="true"</code>
	attribute to its definition,
	for example:
	</p>
	<pre>
	<extension
	point="org.eclipse.ui.perspectives">
	<perspective
	name="%perspectiveName"
	icon="icons/sample.gif"
	<b>fixed="true"</b>
	class="org.eclipse.ui.tutorials.rcp.part3.RcpPerspective"
	id="org.eclipse.ui.tutorials.rcp.part3.RcpPerspective">
	</perspective>
	</extension>
	</pre>
	<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</h2>
	<p>
	Letting you configure all the menus was one of the first
	requirements of the RCP.
	There are two ways to add menus in an RCP application:
	</p>
	<ul>
	<li><code>WorkbenchAdvisor.fillActionBars</code>
	<li><code>org.eclipse.ui.actionSets</code> in the plug-in manifest
	</ul>
	<p>
	<code>fillActionBars</code> is the only way to reference built-in
	Workbench actions, so we'll use it for that purpose.
	Everything else can be contributed by the <code>actionSets</code> extension point.
	Both methods will be demonstrated here.
	Although the example application does not use
	toolbars, they are very similar to menus.
	</p>
	<p>
	First let's take a look at <code>fillActionBars</code>:
	</p>
	<pre>
	public void fillActionBars(
	IWorkbenchWindow window,
	IActionBarConfigurer configurer,
	int flags) {
	super.fillActionBars(window, configurer, flags);
	<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1"> if ((flags & FILL_MENU_BAR) != 0) {
	fillMenuBar(window, configurer);
	}
	}
	</pre>
	<p>
	<code>fillActionBars</code> is takes a flags parameter
	(<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">)
	that indicates what
	the code should really do.
	There are flag bits for filling in the menu bar, the tool bar,
	the status line, and even a bit for whether or not this is a fake
	request for preference dialogs (<code>FILL_PROXY</code>).
	The author has had some bad experiences with flags like this,
	so the example code just calls a helper function called <code>fillMenuBar</code>
	to do the actual filling.
	Here's the code for <code>fillMenuBar</code>:
	</p>
	<pre>
	private void fillMenuBar(
	IWorkbenchWindow window,
	IActionBarConfigurer configurer) {
	IMenuManager menuBar = configurer.getMenuManager();
	menuBar.add(createFileMenu(window));
	menuBar.add(createEditMenu(window));
	menuBar.add(createWindowMenu(window));
	menuBar.add(createHelpMenu(window));
	}
	</pre>
	<p>
	For this example we want to create four top-level
	menus: File, Edit, Window, and Help.
	These correspond to the menus of the same name
	in the Eclipse IDE.
	For a real application you may not want all these,
	or you might want to call them something different.
	See figure 1 for an example.
	</p>

	<img src="images/complete.png">
	<p><b>Figure 1. The Workbench menu bar is defined
	in the <code>fillActionBars</code> method of <code>WorkbenchAdvisor</code>,
	and then added to by the manifests of
	all plug-ins that extend <code>org.eclipse.ui.actionSets</code>.
	</b></p>

	<p>
	The code for all these methods can be found in the example project.
	Let's just take a closer look at one of of them, the File menu:
	</p>

	<pre>
	private MenuManager createFileMenu(IWorkbenchWindow window) {
	<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1"> MenuManager menu = new MenuManager(Messages.getString("File"), //$NON-NLS-1$
	IWorkbenchActionConstants.M_FILE);
	<img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2"> menu.add(new GroupMarker(IWorkbenchActionConstants.FILE_START));
	menu.add(new GroupMarker(IWorkbenchActionConstants.MB_ADDITIONS));
	<img src="images/tag_3.gif" height="13" width="24" align="center" alt="#3"> menu.add(ActionFactory.QUIT.create(window));
	menu.add(new GroupMarker(IWorkbenchActionConstants.FILE_END));
	return menu;
	}
	</pre>
	<p>
	All these menus work the same way.
	First you create a MenuManager for the menu
	(<img src="images/tag_1.gif" height="13" width="24" align="center" alt="#1">)
	using the message file to lookup the actual human-readable title.
	Then you add all the menu items and return the manager.
	See the references section for more information about defining views and menus.
	Next, you create some placeholders
	(<img src="images/tag_2.gif" height="13" width="24" align="center" alt="#2">)
	where additional
	menu items can be added by plug-ins,
	and one real action supplied by the Workbench: the Quit action
	(<img src="images/tag_3.gif" height="13" width="24" align="center" alt="#3">).
	A list of supported Workbench actions can be found by
	looking at the Javadoc for <code>ActionFactory</code> and
	<code>ContributionItemFactory</code>.
	</p>
	<p>
	<img src="images/note.gif" alt="Note: " width="62" height="13">
	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 sample code that accompanies this tutorial was created by looking at the
	<code>IDEWorkbenchAdvisor</code> class used by the Eclipse IDE.
	</p>

	<h2>Help</h2>
	<p>
	One of the coolest features of the RCP is its help system.
	Simply by providing the table of contents in
	XML format and the documents in HTML,
	you can give your users a searchable help
	system with no coding on your part.
	First, you add an extension to your plug-in manifest like this:
	</p>
	<pre>
	<extension
	point="org.eclipse.help.toc">
	<toc
	file="book.xml"
	primary="true">
	</toc>
	</extension>
	</pre>

	<p>
	Then you create a table of contents file (book.xml in this example)
	to define a hierarchy of help topics.
	Not all the topics have to be in the contents but it is
	good practice to do so.
	Here's an example you can use to get started:
	</p>
	<pre>
	<toc label="RCP Help Sample" topic="html/book.html">
	<topic label="Overview" href="html/overview.html"/>
	</toc>
	</pre>
	<p>
	See the references section for more information on writing
	and organizing help files, including internationalization.
	</p>
	<p>
	When you're debugging or deploying an RCP application
	that includes help you'll need to include
	several more help related plug-ins
	in addition to those listed in part 1 of the tutorial.
	Here's the current list (subject to change in future versions):
	</p>
	<ul>
	<li><code>org.apache.ant</code>
	<li><code>org.apache.lucene</code>
	<li><code>org.eclipse.help.appserver</code>
	<li><code>org.eclipse.help.base</code>
	<li><code>org.eclipse.help.ui</code>
	<li><code>org.eclipse.help.webapp</code>
	<li><code>org.eclipse.tomcat</code>
	</ul>
	<p>
	See <code>createHelpMenu()</code> in the example for code
	to add the Help Contents action to your Help menu.
	When you select it, this action will fire up a
	help browser like the one shown in figure 2.
	</p>

	<img src="images/help.png">
	<p><b>Figure 2. The Rich Client Platform provides a
	full featured online help framework so you don't have to.
	All you do is provide the content.
	</b></p>

	<h2>Build.properties</h2>
	<p>
	As you add more resources to your plug-in such as html files,
	icons, the help table of contents, and so forth,
	don't forget to update your build.properties file to
	include all the files and/or directories that need to be
	available to the plug-in at run time.
	Here is the updated build.properties XML file containing everything
	needed for the example in this section:
	</p>
	<pre>
	bin.includes = plugin.xml,\
	*.jar,\
	part3.jar,\
	plugin.properties,\
	<b>book.xml,\</b>
	<b>html/,\</b>
	<b>icons/</b>
	source.part3.jar = src/
	</pre>

	<h2>Conclusion</h2>
	<p>
	In this part of the tutorial, we
	added a simple view, some menus, and help files
	to a create a sample RCP application.
	Hopefully you can can use this example as a reference in
	your own projects.
	All the sample code for this part may be viewed at the
	<a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ui.tutorials.rcp.part3">Eclipse project here</a>.
	You can use
	<a href="http://dev.eclipse.org/cvshowto.html">Eclipse's built-in CVS client</a>
	to download the source to your workspace.
	</p>
	<p>
	Congratulations!
	If you made it this far, you are
	well on your way to developing your own
	Rich Client Platform applications.
	Take a look at the references below for more information
	and community sites and mailing lists where
	you can meet other people using RCP.
	</p>

	<h2>References</h2>
	<p>
	<a href="http://eclipse.org/articles/Article-RCP-1/tutorial1.html">
	RCP Tutorial Part 1</a><br>
	<a href="http://eclipse.org/articles/Article-RCP-2/tutorial2.html">
	RCP Tutorial Part 2</a><br>
	<a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-ui-home/rcp/index.html">
	Eclipse Rich Client Platform</a><br>
	<a href="http://www.eclipse.org/articles/viewArticle/ViewArticle2.html">
	Creating an Eclipse View</a><br>
	<a href="http://www.eclipse.org/articles/Article-Online%20Help%20for%202_0/help1.htm">
	Contributing a Little Help</a><br>
	<a href="http://www.eclipsepowered.org">
	Eclipse Powered (rich client plug-ins and resources)</a><br>
	</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>