EclipseRCP(英文).doc

Eclipse RCPThis tutorial describes how to develop Eclipse RCP applications. It is based on Eclipse 3.6 (Eclipse Helios).Table of Contents1. Eclipse RCP Overview2. Eclipse Plugin Architecture2.1. Eclipse IDE vrs. Eclipse RCP2.2. Eclipse RCP Architecture2.3. Main components of an Eclipse RCP application2.4. Configuration files3. Installation3.1. Installation3.2. Update an Eclipse Java IDE4. Create your first RCP application4.1. Create a RCP application4.2. Start your RCP application5. Startup process and Advisors6. Run configuration6.1. Overview6.2. Check the runtime configuration7. Commands7.1. Overview7.2. Defining commands7.3. Using commands in menus8. System Tray9. Views9.1. Overview9.2. Create a view9.3. Add the view to your perspective9.4. Result9.5. Add view to perspective via code9.6. Editor / View interaction10. Field Assist and label decorator11. JFace Viewer11.1. Overview11.2. ComboViewer12. Adding a status line12.1. Setup Status line12.2. Shared Status Line13. Perspectives13.1. Adding a perspective to your application13.2. Select the perspective14. Products and Branding14.1. Application versus Product14.2. Product Configuration14.3. Create your product configuration14.4. Dependencies14.5. Launch your product14.6. Splash Screen14.7. Branding your product14.8. Customizing the start icon and launcher arguments15. Deploy your product16. Tips and Tricks16.1. Save users layout16.2. Finding unused dependencies16.3. Deploy your own JRE with your RCP application16.4. Multi-User settings17. Questions and Discussion18. Links and Literature18.1. Source Code18.2. Eclipse Resources18.3. vogella Resources1. Eclipse RCP OverviewEclipse RCP allows developers to use the Eclipse platform to create flexible and extensible desktop applications. Eclipse is build upon aplugin architecture . Plugins are the smallest deployable and installable software components of Eclipse. A plugin is a collection of files and a configuration file (MANIFEST.MF) which describes the plugin and its dependencies. The following picture show the content of an example plugin.This plugin architecture allows the Eclipse applications to get extended by third parties. Eclipse RCP provides the same modular concept for stand-alone applications.This tutorial will introduce you to the exciting world of development of Eclipse RCP applications.2. Eclipse Plugin Architecture2.1. Eclipse IDE vrs. Eclipse RCPAn Eclipse application consists out of plugins.From the Eclipse RCP perspective the Eclipse IDE is only one potential configuration of certain plugins. The components of the Eclipse IDE are primary the following.An Eclipse RCP application use only parts of these components. It is possible to design headless Eclipse based applications, then only the runtime is necessary. An Eclipse RCP application typically uses:If you want to use certain functionality in your Eclipse RCP application you have to use the plugins which provide this functionality.The OSGi runtime provides the framework to run the modular application. SWT is the standard UI component library used by Eclipse andJFace provides some convenient API on top of SWT. The workbench provides the application frame in which all other UI components are displayed.2.2. Eclipse RCP ArchitectureEclipse application are build as a number of plugins. Plugins define their API and their dependencies. The basis for this architecture is the runtime environment Equinox which is the reference implementation of OSGI . Eclipse uses the term Plugin and OSGi uses the term bundle, but both terms mean the same.The OSGi specification defines how Eclipse plugins defines:their API - public classes which can be used by other pluginstheir dependencies - package or plugins which are required for the plugin to run correctlyIn addition to this definition based on OSGi you can also use and define extension-points in Eclipse applications. Extension-points define possibilities for functionality contributions ( code and non-code ) by other plugins.Extensions and extension-points are described in the file plugin.xml. This file is a XML file which can be edited via the PDE (Plugin Development Environment) which provides a user interface for editing this file. The extensions are collected when the Eclipse RCP application is started. The information in the extension points is converted in so called descriptors and stored in registries.A plugin can use extensions, e.g. provide functionality to these extension points.2.3. Main components of an Eclipse RCP applicationThe minimal required plugins to create and run an minimal Eclipse RCP application (with UI) are the two plugins org.eclipse.core.runtime and org.eclipse.ui. Based on these components an Eclipse RCP application must define the following elements:Main program - A RCP main application class implements the interface IApplication. This class can be viewed as the equivalent to the main method for standard Java application. Eclipse expects that the application class is defined via the extension point org.eclipse.core.runtime.application.A Perspective - defines the layout of your application. Must be declared via the extension point org.eclipse.ui.perspective.Workbench Advisor- invisible technical component which controls the appearance of the application (menus, toolbars, perspectives, etc)2.4. Configuration filesAn Eclipse RCP application has two main configuration files.MANIFEST.MF - contains the OSGi configuration information.plugin.xml - Information about the extensions and extension points3. Installation3.1. InstallationOn the webpage of E , click on DOWNLOADS. Download the package Eclipse for RCP/Plug-in Developers. Extract the download to your harddisk. Avoid having special characters or spaces in the path to Eclipse.3.2. Update an Eclipse Java IDEIn case you have downloaded the Eclipse Java IDE (or any other non RCP flavor) distribution you can use the Eclipse Update Manager to install the plugins required for RCP development. See Eclipse Update Manager for details on using the update manager.Install General Purpose Tools - Eclipse Plug-in Development Environment and Eclipse RCP Plug-in Developer Resources from the Helios update site. You may have to remove the Group items by category flag to see these features.4. Create your first RCP applicationThe following gives a quick guide on how to create a simple RCP application. It assumes that you already have some knowledge in using the Eclipse IDE for standard Java development. .4.1. Create a RCP applicationIn Eclipse select File- New Project. From the list select Plug-In Project.Give your plugin the name ro.first .Press Next and make the following settings. As we are going to develop a RCP application, select Yes at the question Would you like to create a rich client application.TipIn this tutorial I will use the following: create a RCP project to indicate that you should create a new plugin project with flag Would you like to create a rich client application enabled.Press next and select the template Hello RCP .Press next and select Add branding and press Finish.As a result a project with the following project structure will be created. Have a look at the different files especially the Java files to get a first feeling about the project structure.4.2. Start your RCP applicationOpen the file MANIFEST.MF by double-clicking on it. You should see an editor and the tab Overview should be selected. Click the link Launch an Eclipse Application.The result should look like the following:Congratulations, you have created your first RCP application.5. Startup process and AdvisorsDuring the startup of an Eclipse RCP application the Eclipse runtime will evaluate which class is defined via the org.eclipse.core.runtime.application extension point. This class will be loaded and creates and runs a Workbench. The Workbench is configured via a WorkbenchAdvisor. The Workbench will start a WorkbenchWindow which is configured via a WorkbenchWindowAdvisor. This WorkbenchWindow will create the toolbar of the application which can get configured at startup via the ActionBarAdvisor.Each adviser allow to configure certain behavior of the application, e.g. the WorkbenchAdvisor allows to perform certain actions at startup or shutdown by overriding the methods preStartUp() and preShutdown().6. Run configuration6.1. OverviewA run configuration in Eclipse defines the environment under which your application will be started, e.g. compiler flag, plugin (classpath) dependencies etc. Sometimes a run configuration is called launch configuration. If you start your RCP application a run configuration will be automatically created for you.To see and edit your run configuration select the file MANIFEST.MF, right-click on it and select - Run As - Run ConfigurationsIn the field location you specify their the files will be created which are necessary to run your RCP application.6.2. Check the runtime configurationOn the Plug-ins Tab select Validate plug-ins prior to launching. This will check if you have all required plugins in your launch configuration. If this check reports that some plugins are missing, try clicking the Add Required-Plug-Ins button.TipThis may solve errors like One or more bundles are not resolved because the following root constraints are not resolved or java.lang.RuntimeException: No application id has been found.On the tab Arguments you find the parameter -consoleLog. This option allows to see errors in the RCP application in the console view and is very helpful to identify problems. .TipOther nice parameters are -console (which will give you a OSGI console where you can check the status of your application) and -noExit (which will keep the OSGI console open even if the application ends / crashes).7. Commands7.1. OverviewA command is a declarative description of a component and is independent from the implementation details. A command can be categorized and a hot key (key binding) can be assigned to it. Commands can be used in menus, toolbars and / or context menus. The following will give demonstrates the usage of commands in menus. For details on commands see Eclipse Commands - TutorialTipCommands are superior to Actions. In my opinion Actions should be marked as depreciated. See Bug for deprecating Actions7.2. Defining commandsWe will create a command which will exit the application. Create a new RCP project mands.first using the Hello RCP template. Click on the plugin.xml and select the Extensions tab. Press the Add button.Search for the extension mands. Select it and press finish.Create a new command by right-clicking on your extension point and by selecting New - command.TipIf you only see an Generic entry you most likely have not downloaded Eclipse for RCP/Plug-in Developers. Please see Eclipse Installation .Set the ID to mands.Exit and the name to Exit. Enter the class mands.ExitHandler as defaultHandler.Press the hyperlink defaultHandler to create the class which should extend mands.AbstractHandler. package mands;import mands.AbstractHandler;import mands.ExecutionEvent;import mands.ExecutionException;import org.eclipse.ui.handlers.HandlerUtil;public class ExitHandler extends AbstractHandler Override public Object execute(ExecutionEvent event) throws ExecutionException HandlerUtil.getActiveWorkbenchWindow(event).close(); return null; 7.3. Using commands in menusThe command which we defined should be used in a menu. Add the extension point org.eclipse.ui.menus to your application similar to adding the extension mands. Right click on the extension point and select new - menuContribution.Create a new menu contribution with the location URI menu:org.eclipse.ui.main.menu. Make sure this URL is correct otherwise your menu will not be shown.Right click your menucontribution and select New - Menu. Add a menu with the label File and the id fileMenu.Select your menu, right-click on it, select New- Command. Maintain your commandID. Set the label to Exit and the tooltip to Exits the application.Your work should result in a plugin.xml file which looks like the following. Run the example. You should see menu with the file and if you select the Exit entry you application should exit.8. System TrayThe following add an icon for the RCP application to the system tray and adds a menu to this icon. We add the functionality that if the window is minimized then the program is not visible in the taskpane (only via the tray icon).Create a new project ro.traytest. Use the Hello RCP as a template. Create a command which the id ro.traytest.exitCommand which exists the application.Open the class ApplicationWorkbenchWindowAdvisor and maintain the following code. package ro.traytest;import org.eclipse.swt.SWT;import org.eclipse.swt.events.ShellAdapter;import org.eclipse.swt.events.ShellEvent;import org.eclipse.swt.graphics.Image;import org.eclipse.swt.graphics.Point;import org.eclipse.swt.widgets.Event;import org.eclipse.swt.widgets.Listener;import org.eclipse.swt.widgets.Menu;import org.eclipse.swt.widgets.MenuItem;import org.eclipse.swt.widgets.Shell;import org.eclipse.swt.widgets.Tray;import org.eclipse.swt.widgets.TrayItem;import org.eclipse.ui.IWorkbenchWindow;import org.eclipse.ui.application.ActionBarAdvisor;import org.eclipse.ui.application.IActionBarConfigurer;import org.eclipse.ui.application.IWorkbenchWindowConfigurer;import org.eclipse.ui.application.WorkbenchWindowAdvisor;import org.eclipse.ui.handlers.IHandlerService;import org.eclipse.ui.plugin.AbstractUIPlugin;public class ApplicationWorkbenchWindowAdvisor extends WorkbenchWindowAdvisor private IWorkbenchWindow window; private TrayItem trayItem; private Image trayImage; private final static String COMMAND_ID = ro.traytest.exitCommand; public ApplicationWorkbenchWindowAdvisor( IWorkbenchWindowConfigurer configurer) super(configurer); public ActionBarAdvisor createActionBarAdvisor( IActionBarConfigurer configurer) return new ApplicationActionBarAdvisor(configurer); public void preWindowOpen() IWorkbenchWindowConfigurer configurer = getWindowConfigurer(); configurer.setInitialSize(new Point(400, 300); configurer.setShowCoolBar(false); configurer.setShowStatusLine(false); configurer.setTitle(Hello RCP); /$NON-NLS-1$ / As of here is the new stuff Override public void postWindowOpen() super.postWindowOpen(); window = getWindowConfigurer().getWindow(); trayItem = initTaskItem(window); / Some OS might not support tray items if (trayItem != null) minimizeBehavior(); / Create exit and about action on the icon hookPopupMenu(); / Add a listener to the shell private void minimizeBehavior() window.getShell().addShellListener(new ShellAdapter() / If the window is minimized hide the window public void shell