Friday, May 8, 2009

Context Sensitive Help in Eclipse (Version 3.4 - Ganymede)

Introduction:

This article will explain and walk you through on how to add context sensitive help to your Eclipse application. Also, it touches upon how to implement programmatic help in Eclipse.

Adding context extension:

Open plugin.xml of your help plugin (or your source plugin, if you have help files in your source plugin itself) . Go to extensions and add org.eclipse.help.contexts extension point. Create contexts element inside it which has two attributes - file and plugin. The file attribute points to your contexts.xml (we will discuss the details of contexts.xml below) and the plugin attribute points to the plugin for which context sensitive help is needed. The plugin attribute is very useful, and allows any plugin to contribute to the context help of other plugins. This provides extensibility. Below is an example of this extension point:

<extension
point="org.eclipse.help.contexts">
<contexts
file="contexts.xml"
plugin="com.mycompany.xyz">
</contexts>
</extension>

Contexts.xml:

This file lists the various context ids. The root element is contexts and it can have many context elements. Each context has id and title attributes and it has description and topic elements. A context can have multiple topics each pointing to a html location. PDE has support for editing contexts xml file. You should be able to right click on contexts and add context, edit attributes of context etc., using the PDE editor. Below is an example of a sample contexts xml file:

<contexts>
<context id="package_explorer_view" title="Package Explorer View">
<description>Short description of package explorer view
<topic href="html/views/packageExplorer.html" label="Package Explorer View"/>
</context>
<context id="java_editor" title="Java Editor">
<description>Short description of java editor
<topic href="html/editors/javaEditor.htmll" label="Java Editor"/>
</context>
</contexts>

Setting context ids in the code:

Now that we have defined the contexts file and the context ids, it is time to associate the views and editors in the application to those context ids. You can set the context ids for your control using this:

IWorkbenchHelpSystem helpSystem = PlatformUI.getWorkbench().getHelpSystem();
helpSystem.setHelp(control, "com.mycompany.xyz.package_explorer_view");

Note that context id has the plugin name prefixed to it. The contex id in itself (i.e without the prefix) should not have whitespaces or periods.

Also, context id's are inherited by the child controls. You can override by setting the context id for each of your child control. If not, they would use the parent context id.

Invoking Help:

Now, whenever you press F1, it will display context sensitive help. It can either appear in infopopup or the Help view. You can control that using the preference in
Window->Preferences->Help. It has option to show context sensitive help in either the help view or in the infopopup. The bottom of the infopopup also has option to show the context in help view.

Adding Dynamic Help menu item:

Dynamic Help view is the same help view which appears when F1 is pressed. If you wish, you can add it to your Help menu (like in Eclipse IDE) by adding org.eclipse.ui.help.dynamicHelp command under your menu. Also, don't forget to register this action in your ApplicationActionBarAdvisor class.

action = ActionFactory.DYNAMIC_HELP.create(window);
this.register(action);

The dynamic help view changes content based on the active selection. For example, if you are in package explorer, it will show help for that view and then when you move selection from there to java editor, it will display the contents related to the java editor.

Programmatic Help:

Eclipse also provides API to access the help system programmatically. For example, if you want to open the global help or the context help for a particular editor upon pressing a button, you can do so by using the API. IWorkbenchHelpSystem has various methods to access help. Some of the common useful ones are:

displayHelp();

displayHelp(String contextId);

displayHelpResource(String htmlUrl);

setHelp(Control control, String contextId);

Below is a code snippet for displaying the context help when help button is pressed:

Button help = new Button(buttonsComposite, SWT.PUSH);
help.setText("Help");
GridData gridData = new GridData(SWT.BEGINNING, SWT.BEGINNING, false, false);
help.setLayoutData(gridData);
help.addSelectionListener(new SelectionAdapter() {
public void widgetSelected(SelectionEvent evt) {
IWorkbenchHelpSystem helpSystem = PlatformUI.getWorkbench().getHelpSystem();
helpSystem.displayHelp("com.mycompany.xyz.java_editor");
}
});

Conclusion:

We saw how to add the required contexts extension, details of contexts xml file and how to associate context ids in the code. We also discussed about adding dynamic help, how to add it to the menu and how to access the help system programmatically. Hope this article helps you in implementing context sensitive help in your eclipse application.

8 comments:

Ilango said...

Raja, I can't follow this line: "Open plugin.xml of your help plugin (or your source plugin, if you have help files in your source plugin itself) "

Please help me understand this. Thanks.

Raja said...

Hi Ilango,

Best practice is to have documentation for your source plugin in a separate plugin i.e for every source plugin have a corresponding help/documentation plugin. If you follow this, open the plugin.xml of your help plugin. If not, use plugin.xml from your source plugin.

Hope this helps,

- Raja.

Raja said...

Hi Ilango,

You can also look at my other previous post for more info on Eclipse Help in general.

http://rajakannappan.blogspot.com/2009/05/working-with-eclipse-help-system.html

gunvant said...

Hey raja,
I want to open dynamic help context on selection of a text in the editor and want to display that text in the help window. How can i achiecve this. I will be very much thankful if you could provide code snippet.
Thanks
Gunvant

chbohm said...

Hi Raja,
here is a very good page where you can find information on how we could use DITA in order to create Conext Sensitive Help

Eclipse RCP Documentation Development with DITAworks

Watson Zion said...

Best train is to have documentation for your candy man plugin in a am a foil to plugin i.e for aside candy man plugin have a like two peas in a pod help/documentation plugin. If you copy this, unmask the plugin.xml of your threw in one lot with plugin. If not, evaluate plugin.xml from your source plugin. I prefer to bring to light Research Paper Writing Services dynamic threw in one lot with context on levy of a matter in hand in the editor and hast a preference for to let cat out of bag that matter in hand in the threw in one lot with window. How bouncecel i get ahead this. I will be literally much appreciative if you could laid at one feet code snippet.

Wagner Zack said...

If not, assess plugin.xml from your source module. I like to convey to light element tossed in one parcel with setting on collect of a matter close by in the editorial manager and hast an inclination for to give feline a chance to Airport Taxis London out of pack that matter close by in the tossed in one part with window. In the event that you duplicate this, unmask the plugin.xml of your tossed in one part with module. If not, assess plugin.xml from your source module.

amy kristan said...

https://vtightgel-review.com