Support free tutorials

vogella training Training Books

Adding Help to Eclipse RCP Applications - Tutorial

Lars Vogel

Version 1.3


Eclipse RCP Help System

This article describes how to add help to an Eclipse RCP application. It is based on Eclipse Indigo (3.7).

Table of Contents

1. Eclipse Help
1.1. Overview
1.2. Extension point
1.3. Internationalization
1.4. Generating Eclipse Help
1.5. Context sensitive help
1.6. ActiveHelp
2. Prerequisites for this tutorial
3. Example
3.1. Project with help
3.2. Adding search and context sensitive help
4. About this website
4.1. Donate to support free tutorials
4.2. Questions and discussion
4.3. License for this tutorial and its code
5. Links and Literature
5.1. Source Code
5.2. Eclipse Help Resources
5.3. vogella Resources

1. Eclipse Help

1.1. Overview

Eclipse has a build-in help system which allows to start and access the help system directly from your Eclipse RCP application. The Eclipse help system is based on HTML, the "" extension points and additional XML files which point to the HTML files.

Via the extension point you describe the first level structure and point to XML files. These XML files contain references to the relevant HTML files.

Typically help content is delivered via separate plug-ins. To use help in your Eclipse RCP project either add the following plug-ins and their dependencies to your product:



  • org.eclipse.equinox.http.jetty

or if you product is feature based add the feature and org.eclipse.ui.forms plug-in to your product configuration file.

Eclipse defines several predefined commands which you can use in your RCP application.

  • "" - Opens the help

  • "" - Open the Search

  • "" - Opens the Help specific for the current selection if this is configured in the application

1.2. Extension point

The following shows an example of an extension for "". The toc entry which has the primary="true" flag set will be treated as a main entry in the help, all others will be treated as subtopics. Topics not flagged as "primary" will not show up in the help hierarchy unless they are linked to from at least one primary toc file. The file attribute points to the XML file which describes the content.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>



The primary toc file defines anchor points to which other toc files can contribute content. For example the following "toc.xml" defines two anchor points "gettingstarted" and "samples". This approach is called "bottom-up composition". Eclipse help files can also be build with a "top-down nesting" approach but this tutorial not only use "bottom-up composition". "Bottom-up composition" allow that the top level toc does not know who is extending its anchors. New plug-ins could add new content to these anchors without the need to change the primary toc. This concept is very close to the extension point mechanism in Eclipse.

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE=""?>

<toc label="Address Book Help" topic="html/toc.html">
   <topic label="Getting Started">
      <anchor id="gettingstarted"/>
   <topic label="Samples">
      <anchor id="samples"/>

The following shows the non primary ""tocgettingstarted.xml" file. Via the href attribute this toc file links the chapters to actual HTML files. The "link_to" attribute points to the anchors of the primary toc.

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE=""?>

<toc label="Getting Started" link_to="toc.xml#gettingstarted"> 
  <topic label="Main Topic"  href="html/gettingstarted/maintopic.html"> 
    <topic label="Sub Topic" href="html/gettingstarted/subtopic.html" /> 
  <topic label="Main Topic 2">
    <topic label="Sub Topic 2" href="html/gettingstarted/subtopic2.html" />

1.3. Internationalization

To support several languages in your help plug-in place the content into a special directory into your plug-in called "nl/language/country" thereby country is optional. For example to provide English and German content use "nl/en" and "nl/de".

The help system will first search in the "nl/language/country" directory, afterwards in the "nl/language" directory and if it does not find anything there then it searches in the root folder of the plug-in directory.

Typically translations of help content are provides via Fragment projects for the primary help plug-in. At runtime the host plug-in and its fragments are merged to one.

1.4. Generating Eclipse Help

Writing the HTML and XML files for the Eclipse help can be time consuming. One frequently used approach is to write Docbook files. Docbook source files can be converted into PDF, HTML and Eclipse help files via the Docbook XSLT stylesheets.

1.5. Context sensitive help

You can add context sensitive help to your application via the extension point "". This extension point defines a file for a certain plug-in.


This file defines Id's and links to the HTML pages of the help system. The file can be maintained with the specialized "Context Help Editor".

<?xml version="1.0" encoding="UTF-8"?>
  <context id="myId">
    <description> This is a sample F1 help string.</description>
    <topic href="contexts/RelatedContext1.html" label="Help Related Topic 1" />
    <topic href="contexts/RelatedContext2.html" label="Help Related Topic 2" />

To assign these id to your SWT controls you can use the following code:

PlatformUI.getWorkbench().getHelpSystem().setHelp(control, "myId"); 

If the user opens the dynamic help via the command "" then the corresponding help is displayed.

1.6. ActiveHelp

You can link from the help to Eclipse commands. This feature is called ActiveHelp and requires that you add a small JavaScript snippet to your HTML code. You find an example for how to use this in the Eclipse help. Search for "Active Help".

2. Prerequisites for this tutorial

This tutorial assumes that you have basic understanding of development for the Eclipse platform. Please see Eclipse RCP Tutorial or Eclipse Plug-in Tutorial if you need any basic information.

3. Example

3.1. Project with help

The following will demonstrate how to create the help in a separated plug-in which contains all help related content.

Create a new Eclipse RCP project "" with the template "RCP application with a view". Create another plug-in (not RCP application) "" with the template "Plug-in with sample help content". Select the following options.

Add the following plugins as dependency to your "" plugin.



  • org.eclipse.equinox.http.jetty

Add the command to "" to the main menu in "". Optionally you can also assign the key "F1" via the extension point "org.eclipse.ui.bindings" to the command.

Create a launch configuration which includes "" and "" and all dependencies and run your application. You should be able to open the help content via the menu.

To understand the structure of the help file check your plugin.xml and you see that the extension point "" is used to point to toc*.xml files which describes the help content.

3.2. Adding search and context sensitive help

You can also add a search dialog and context sensitive help to your application. To do this you add the commands "" and "" to your application. Unfortunately you have to activate these in the "ApplicationActionBarAdvisor" class via the following coding.


import org.eclipse.ui.IWorkbenchWindow;
import org.eclipse.ui.actions.ActionFactory;
import org.eclipse.ui.actions.ActionFactory.IWorkbenchAction;
import org.eclipse.ui.application.ActionBarAdvisor;
import org.eclipse.ui.application.IActionBarConfigurer;

public class ApplicationActionBarAdvisor extends ActionBarAdvisor {

  protected void makeActions(IWorkbenchWindow window) {

  public ApplicationActionBarAdvisor(IActionBarConfigurer configurer) {


Now you can call the help search and the context sensitive help. To define the targets for the context sensitive search create a file "context.xml" in your help plug-in with the following content.

   <context id="message">
      <description>This is the sample context-sensitive help. There is a link to the help content below.</description>
      <topic href="html/gettingstarted/subtopic.html" label="Subtopic" />

You then have to define an extension "" which points to the file "context.xml".


After this you can assign the help to individual controls. For example you can assign the help to your table control.

Text text = new Text(parent, SWT.NONE);
PlatformUI.getWorkbench().getHelpSystem().setHelp(text, "message"); 

4. About this website

4.1. Donate to support free tutorials

Please consider a contribution Support free tutorials if this article helped you. It will help to maintain our content and our Open Source activities.

4.2. Questions and discussion

Writing and updating these tutorials is a lot of work. If this free community service was helpful, you can support the cause by giving a tip as well as reporting typos and factual errors.

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

4.3. License for this tutorial and its code

This tutorial is Open Content under the CC BY-NC-SA 3.0 DE license. Source code in this tutorial is distributed under the Eclipse Public License. See the vogella License page for details on the terms of reuse.

5. Links and Literature

5.1. Source Code

Source Code of Examples

5.3. vogella Resources

The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”. The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.