Difference between revisions of "Rich Client Platform/How-to"

From Eclipsepedia

Jump to: navigation, search
(plugin.xml: The RBE approach)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{RCP}}
 
{{RCP}}
This page is a checklist to get started to build an Eclipse RCP application.
+
This page is a checklist to get started in building an Eclipse RCP application.
 
It is intended to keep as minimal as possible.
 
It is intended to keep as minimal as possible.
  
This was tested on Eclipse 3.4 (Ganymede).
+
This was tested on Eclipse 3.5 (Galileo).
  
 
== IDE ==
 
== IDE ==
Line 11: Line 11:
 
Link "Eclipse for RCP/Plug-in Developers"
 
Link "Eclipse for RCP/Plug-in Developers"
  
Download and unzip: eclipse-rcp-ganymede-*.zip
+
Download and unzip: eclipse-rcp-galileo-*.zip
  
 
Launch Eclipse
 
Launch Eclipse
Line 20: Line 20:
 
== Target ==
 
== Target ==
  
Create directory ''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
 
http://download.eclipse.org/eclipse/downloads
Line 29: Line 31:
  
 
* Delta pack is needed for building to other platforms, or for automated [[#Build|build]].
 
* Delta pack is needed for building to other platforms, or for automated [[#Build|build]].
* If Help ou Update feature is needed, either replace RCP-SDK with platform-SDK, or download individual features from http://www.eclipse.org/platform/
+
* 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.
 
* eclipse-RCP-SDK-*.zip is needed rather than eclipse-RCP-*.zip else extensions won't work in plug-in editor.
  
Line 155: Line 157:
 
* Use an existing product (''plugin_id''.product) if applying (if "Add branding" was checked)
 
* 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)
 
* 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>
If no existing product:
+
''product_name''.product > Overview > Testing > Synchronize (updates plugin.xml) <br>
''product_name''.product > Overview > Specify the product identifier > New > Defining plug-in
+
''product_name''.product > Overview > Testing > Launch <br>
 
+
''product_name''.product > Overview > Testing > Synchronize (updates plugin.xml)
+
''product_name''.product > Overview > Testing > Launch
+
 
''product_name''.product > Overview > Eclipse Product export wizard
 
''product_name''.product > Overview > Eclipse Product export wizard
  
Line 167: Line 166:
 
Creating a feature is required for [[#Update|update]].
 
Creating a feature is required for [[#Update|update]].
  
File > New > Project > Feature Project > Next > Project name > ''feature_id''
+
File > New > Project > Feature Project > Next > Project name > ''feature_id'' <br>
 
feature.xml > Plug-ins > Add > ''plugin_id''
 
feature.xml > Plug-ins > Add > ''plugin_id''
  
''product_name''.product > Overview > The product configuration is based on > Features
+
''product_name''.product > Overview > The product configuration is based on > Features <br>
''product_name''.product > Configuration > Add > org.eclipse.rcp
+
''product_name''.product > Configuration > Add > org.eclipse.rcp <br>
 
''product_name''.product > Configuration > Add > ''feature_id''
 
''product_name''.product > Configuration > Add > ''feature_id''
  
Line 187: Line 186:
 
plugin_''xx''.properties:
 
plugin_''xx''.properties:
 
   key=''Translated value''
 
   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 ===
 
=== RCP ===
Line 331: Line 343:
 
   org.eclipse.ui/DOCK_PERSPECTIVE_BAR=topRight
 
   org.eclipse.ui/DOCK_PERSPECTIVE_BAR=topRight
 
   org.eclipse.ui/SHOW_TRADITIONAL_STYLE_TABS=false
 
   org.eclipse.ui/SHOW_TRADITIONAL_STYLE_TABS=false
 +
 +
== Status Line ==
 +
 +
WorkbenchWindowAdvisor.preWindowOpen:
 +
 +
  getWindowConfigurer ().setShowStatusLine (true);
 +
 +
ViewPart:
 +
 +
  getViewSite ().getActionBars ().getStatusLineManager ().setMessage ("message");
  
 
[[Category:RCP]]
 
[[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);

Latest revision as of 17:31, 4 February 2011

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

[edit] 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

[edit] 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

[edit] 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

[edit] View

plugin.xml > Extensions > Add > org.eclipse.ui.views > right-click > New > View > id, class

[edit] 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);

[edit] 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);

[edit] 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

[edit] Command

plugin.xml > Extensions > org.eclipse.ui.commands > right-click > New > command > defaultHandler > Superclass > org.eclipse.core.commands.AbstractHandler

[edit] 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

[edit] 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);

[edit] 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);

[edit] View Toolbar

plugin.xml > Extensions > org.eclipse.ui.menus > right-click > New > menuContribution > locationURI = toolbar:view_id > right-click > New > command > commandId > Browse

[edit] 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)

[edit] 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

[edit] 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

[edit] Localization

[edit] 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.

[edit] 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

[edit] Strings

Source > Externalize Strings > Use Eclipse's string externalization

[edit] 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

[edit] 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

[edit] 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);

[edit] 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

[edit] 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

[edit] Status Line

WorkbenchWindowAdvisor.preWindowOpen:

 getWindowConfigurer ().setShowStatusLine (true);

ViewPart:

 getViewSite ().getActionBars ().getStatusLineManager ().setMessage ("message");

[edit] 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.

[edit] 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);