Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Rich Client Platform/How-to
RCP |
Home |
How to Contribute |
FAQ |
This page is a checklist to get started in building an Eclipse RCP application. It is intended to keep as minimal as possible.
This was tested on Eclipse 3.5 (Galileo).
Contents
IDE
http://www.eclipse.org/downloads/
Link "Eclipse for RCP/Plug-in Developers"
Download and unzip: eclipse-rcp-galileo-*.zip
Launch Eclipse
Open PDE (Plug-in Development Environment) perspective: Window > Open Perspective > Other > Plug-in Development
Target
Target Platform is used to run the applications/plugins you build with Eclipse RCP. Although it is possible to run your applications/plugins using your Eclipse IDE installation, this is not recommended.
Create directory target in a folder of your choice.
http://download.eclipse.org/eclipse/downloads
Download and unzip in target: eclipse-RCP-SDK-*.zip, eclipse-*-delta-pack.zip
- Delta pack is needed for building to other platforms, or for automated build.
- If Help or Update feature is needed, either replace RCP-SDK with platform-SDK, or download individual features from http://www.eclipse.org/platform/
- eclipse-RCP-SDK-*.zip is needed rather than eclipse-RCP-*.zip else extensions won't work in plug-in editor.
Window > Preferences > Plug-in Development > Target Platform > Browse > target/eclipse > OK > Reload
Plug-in
File > New > Project > Plug-in Project > Next > Project name > Next > Rich Client Application > Yes > Next > Hello RCP > Next > Add branding > Finish
plugin.xml > Overview > Testing > Launch
View
plugin.xml > Extensions > Add > org.eclipse.ui.views > right-click > New > View > id, class
Perspective
plugin.xml > Extensions > org.eclipse.ui.perspectives > perspective > class
public void createInitialLayout (IPageLayout layout) { layout.addView ("view_id", IPageLayout.LEFT, 0.5f, layout.getEditorArea ()); layout.getViewLayout ("view_id").setCloseable (false); }
WorkbenchWindowAdvisor.preWindowOpen:
configurer.setShowPerspectiveBar (true); configurer.setShowCoolBar (true);
Editor
plugin.xml > Extensions > Add > org.eclipse.ui.editors > id, class, icon
To open editor:
IWorkbenchPage page; IEditorInput input; page = PlatformUI.getWorkbench ().getActiveWorkbenchWindow ().getActivePage (); // else if in ViewPart // page = getSite ().getPage (); page.openEditor (input, "editor_id");
EditorPart.init:
setSite (site); setInput (input);
Debug
In case something goes wrong:
Run > Run Configurations > Main > Clear workspace
Run > Run Configurations > Arguments > Program arguments > -consoleLog
Run > Run Configurations > Plug-ins > Validate plug-ins automatically
Run > Run Configurations > Plug-ins > Add Required Plug-ins
Command
plugin.xml > Extensions > org.eclipse.ui.commands > right-click > New > command > defaultHandler > Superclass > org.eclipse.core.commands.AbstractHandler
Menu
plugin.xml > Extensions > org.eclipse.ui.menus > right-click > New > menuContribution > locationURI = menu:org.eclipse.ui.main.menu > right-click > New > menu > right-click > New > command > commandId > Browse
plugin.xml > Extensions > org.eclipse.ui.menus > right-click > New > menuContribution > locationURI = popup:view_id > right-click > New > command > commandId > Browse
ViewPart.createPartControl:
Viewer viewer; MenuManager menuManager = new MenuManager (); Menu menu = menuManager.createContextMenu (viewer.getControl ()); viewer.getControl ().setMenu (menu); getSite ().registerContextMenu (menuManager, viewer);
Toolbar
plugin.xml > Extensions > org.eclipse.ui.menus > right-click > New > menuContribution > locationURI = toolbar:org.eclipse.ui.main.toolbar > right-click > New > toolbar > right-click > New > command > commandId > Browse
WorkbenchWindowAdvisor.preWindowOpen:
configurer.setShowCoolBar (true);
View Toolbar
plugin.xml > Extensions > org.eclipse.ui.menus > right-click > New > menuContribution > locationURI = toolbar:view_id > right-click > New > command > commandId > Browse
Key Binding
plugin.xml > Extensions > org.eclipse.ui.commands > right-click > New > keyBinding
- keyConfigurationId = org.eclipse.ui.defaultAcceleratorConfiguration
- commandId (there is no Browse button)
- keySequence = M1+A (this is Ctrl-A)
Product
Creating a product is required for branding and automatic build.
File > New > Product Configuration > File name > product_name.product > Initialize the file content:
- Use an existing product (plugin_id.product) if applying (if "Add branding" was checked)
- Use a launch configuration (plugin_id.application) if applying (if application was launched)
If no existing product: product_name.product > Overview > Specify the product identifier > New > Defining plug-in
product_name.product > Overview > Testing > Synchronize (updates plugin.xml) product_name.product > Overview > Testing > Launch product_name.product > Overview > Eclipse Product export wizard
Feature
Creating a feature is required for update.
File > New > Project > Feature Project > Next > Project name > feature_id feature.xml > Plug-ins > Add > plugin_id
product_name.product > Overview > The product configuration is based on > Features product_name.product > Configuration > Add > org.eclipse.rcp product_name.product > Configuration > Add > feature_id
Localization
plugin.xml
plugin.xml > Overview > Exporting > Externalize Strings Wizard
plugin.properties:
key=Default value
Create for each language xx (ISO 639 language code) a file plugin_xx.properties
plugin_xx.properties:
key=Translated value
RCP
http://download.eclipse.org/technology/babel/babel_language_packs/
Unzip BabelLanguagePack-eclipse-*.zip into target
Window > Preferences > Plug-in Development > Target Platform > Reload
Run > Run Configurations > Plug-ins > Add Required Plug-ins
Strings
Source > Externalize Strings > Use Eclipse's string externalization
Preferences
If no need for preference scopes
http://www.eclipse.org/eclipse/platform-core/documents/user_settings/faq.html
Get preference value:
Activator.getDefault ().getPluginPreferences ().getString ("preference_id");
Preference page: plugin.xml > Extensions > Add > org.eclipse.ui.preferencePages > right-click > New > page > class > Superclass > FieldEditorPreferencePage
FieldEditorPreferencePage:
protected IPreferenceStore doGetPreferenceStore () { return Activator.getDefault ().getPreferenceStore (); } protected void createFieldEditors () { addField (new StringFieldEditor ("preference_id", "label", getFieldEditorParent ())); }
Command org.eclipse.ui.window.preferences
Update
See also feature
File > New > Project > Update Site Project
site.xml > Archives > URL, Description
site.xml > Site Map > Add Feature > feature_id
site.xml > Site Map > Build All
Copy to URL: site.xml, plugins, features
feature.xml > Overview > Update Site URL
feature.xml > Included Features > Add > org.eclipse.rcp
feature.xml > Plug-ins > Add > org.eclipse.core.net, org.eclipse.equinox.security, org.eclipse.ui.forms, org.eclipse.update.core, org.eclipse.update.ui
plugin.xml > Dependencies > Add > org.eclipse.update.core, org.eclipse.update.ui
Run > Run Configurations > Plug-ins > Add Required Plug-ins
Add command IHandler
IHandler.execute:
BusyIndicator.showWhile (HandlerUtil.getActiveShell (event).getDisplay (), new Runnable () { public void run () { String label = Platform.getResourceBundle (Platform.getBundle ( "org.eclipse.update.ui")).getString ("actionSets.softwareUpdates.label"); UpdateManagerUI.openInstaller (HandlerUtil.getActiveShell (event), new UpdateJob (label, false, false)); } });
WorkbenchWindowAdvisor.preWindowOpen:
configurer.setShowProgressIndicator (true);
Test with exported product, not with product launched from IDE
Help
Add command org.eclipse.ui.help.helpContents
plugin.xml > Dependencies > Add > org.eclipse.help.ui, org.eclipse.help.webapp
plugin.xml > Extensions > Add > org.eclipse.help.toc > Available templates > Help Content
product_name.product > Configuration > Add > org.eclipse.help
build.properties > Binary build > check html, icons, toc.xml, etc.
ActionBarAdvisor.makeActions:
IAction helpAction = ActionFactory.HELP_CONTENTS.create (window); register (helpAction);
Build
Automatic (headless) build
File > New > Project > General > Project
Copy build.properties and customTargets.xml from: eclipse/plugins/org.eclipse.pde.build_*/templates/headless-build
build.properties (edit with properties file editor):
product=/plugin_id/product_name.product archivePrefix configs=win32,win32,x86 & linux,gtk,x86 (*,*,* does not work) buildDirectory=${builder}/build base=path_to_target
customTargets.xml:
<target name="preSetup"> <copy todir="${buildDirectory}/plugins/plugin_id"> <fileset dir="${builder}/path_to_plugin" /> </copy> <copy todir="${buildDirectory}/features/feature_id"> <fileset dir="${builder}/path_to_feature" /> </copy> </target>
product_name.product > Program Launcher > Launcher Name
java -jar eclipse/plugins/org.eclipse.equinox.launcher_*.jar -application org.eclipse.ant.core.antRunner -buildfile eclipse/plugins/org.eclipse.pde.build_*/scripts/productBuild/productBuild.xml
Customization
Create file plugin_customization.ini in plug-in
plugin_customization.ini:
org.eclipse.ui/DOCK_PERSPECTIVE_BAR=topRight org.eclipse.ui/SHOW_TRADITIONAL_STYLE_TABS=false
Status Line
WorkbenchWindowAdvisor.preWindowOpen:
getWindowConfigurer ().setShowStatusLine (true);
ViewPart:
getViewSite ().getActionBars ().getStatusLineManager ().setMessage ("message");
Extension Point
Plug-in with extension point (plugin_id):
plugin.xml > Extension Points > Add > ID=point_id, Name
point_id.exsd > Definition > New Element > Name=element_name
element_name > New Attribute > Name=class_name, Type=java, Implements=package_name.InterfaceName > Implements
point_id.exsd > Definition > extension > New Choice > right-click > New > element_name
plugin.xml > Runtime > Exported Packages > Add > package_name
Activator.start (for example):
IConfigurationElement[] elements = Platform.getExtensionRegistry ().getConfigurationElementsFor ("plugin_id.point_id"); for (IConfigurationElement e : elements) { Object o = e.createExecutableExtension ("class_name"); if (o instanceof InterfaceName) { } }
Plug-in with extension:
MANIFEST.MF > Dependencies > Required Plug-ins > plugin with extension point
MANIFEST.MF > Extensions > Add > plugin_id.point_id > right-click > New > element_name > class_name
Add plug-in with extension to run configuration.
Progress
Job job = new Job ("Job name") { public IStatus run (IProgressMonitor monitor) { final int duration = 10; monitor.beginTask ("Task message", duration); try { for (int i = 0; i < duration; i++) { if (monitor.isCanceled ()) return Status.CANCEL_STATUS; monitor.subTask ("Subtask message"); // ... monitor.worked (1); } } finally { monitor.done (); } return Status.OK_STATUS; } } job.schedule ();
WorkbenchWindowAdvisor.preWindowOpen:
IWorkbenchWindowConfigurer configurer = getWindowConfigurer (); configurer.setShowProgressIndicator (true);