View source for Rich Client Platform/How-to

{{RCP}}
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).

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

== Popup menu ==

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|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 <br>
''product_name''.product > Overview > Testing > Synchronize (updates plugin.xml) <br>
''product_name''.product > Overview > Testing > Launch <br>
''product_name''.product > Overview > Eclipse Product export wizard

== Feature ==

Creating a feature is required for [[#Update|update]].

File > New > Project > Feature Project > Next > Project name > ''feature_id'' <br>
feature.xml > Plug-ins > Add > ''plugin_id''

''product_name''.product > Overview > The product configuration is based on > Features <br>
''product_name''.product > Configuration > Add > org.eclipse.rcp <br>
''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''

Add this line in MANIFEST.MF:
  Bundle-Localization: plugin

Alternately (tested under Helios 3.6), you can run the Externalize Strings Wizard on plugin.xml (and any source files that need it too), then run PDE Tools: Internationalize on the project. This creates a project fragment (of the same name with ".nl1" suffixed) that contains the to-be-localized files.

Move the various .properties files from that project fragment to the source project (e.g. move "myproject.nl1/plugin_fr.properties" to "myproject/plugin_fr.properties", and likewise for any .properties files in subfolders such as OSGI-INF or src). You should then have essentially nothing left in the project fragment, so you can delete it.

Now install the Resource Bundle Editor (RBE) plug-in (from http://sourceforge.net/projects/eclipse-rbe/) by unzipping its plugins directory into your eclipse/plugins directory (restart Eclipse once this is done). Go to Window: Preferences: General: Editors: File Associations, and assign RBE as the default editor for .properties files.

You will now be able to open the .properties files that need localization and edit them accordingly. By keeping matching .properties files co-located, RBE is able to display the original (English) and target language string values side by side, which makes translation less of a chore. RBE is being integrated into Eclipse's Babel project, so it will eventually no longer be necessary to move the .properties files as described earlier: you'll be able to edit them right in the project fragments. Project fragments are nice if you do not want to ship your project with all the various localizations in it (strings, icons, images, help files, etc.), but would rather ship each localization separately.

If you do not use RBE, be aware that .properties files ''must'' use ISO 8859-1 character encoding, which makes some Unicode strings painful to deal with; RBE handles this conversion transparently for you.

=== 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|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");

[[Category:RCP]]

== 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);