Eclipse Platform provides a help system that can be used during creation of the help content for your application. It is very convenient while used inside of the IDE, but needs a special approach if used in the RCP. This article tries to gather the information which may be useful.
Adding Help Support
Basic preparations
As discussed in Eclipse RCP Book and RCP Articles, the help system is not a part of the RCP-Runtime and should be added separately. The question arises where to add at to? If you follow the best practices for packaging of RCP applications, you should have at least one product and the top level feature defined (See Rule 1 of Chapter 23 of Eclipse Rich Client Platform). The top level feature includes the branding plug-in (containing the product definition) and refer to other features (like org.eclipse.rcp, and your functional features). In order to add the help system, you need to add the org.eclipse.help feature in this list.
Platform help buttons
There are several predefined buttons (actions) you can use for calling the help system. These are:
- Help Contents
- Help Search
- Dynamic Help
In order to activate them from your ApplicationActionBarAdvisor just call:
private IWorkbenchAction helpContentsAction;
private IWorkbenchAction helpSearchAction;
private IWorkbenchAction dynamicHelpAction;
protected void makeActions(IWorkbenchWindow window)
{
helpContentsAction = ActionFactory.HELP_CONTENTS.create(window);
dynamicHelpAction = ActionFactory.DYNAMIC_HELP.create(window);
helpSearchAction = ActionFactory.HELP_SEARCH.create(window);
register(helpContentsAction);
register(helpSearchAction);
register(dynamicHelpAction);
}
If you want to do the same declarative, you have to create commands that use the following actionDefinitionIds:
- org.eclipse.ui.help.helpContents
- org.eclipse.ui.help.helpSearch
- org.eclipse.ui.help.dynamicHelp
The same ids are required for registration of key bindings (e.G. Ctrl + F1, Shift + F1, F1 on Win32). Apparently, since these actions adjust their status depending on the state of the system and the plug-ins installed, I could not figure out how to force them to be enabled, when installed in a declarative way. Since they are still provided as ActionFactory (which is legacy due to the changes introduced by new Command Framework), they should be further activated from the ApplicationActionBarAdvisor.
Context-Sensitive Help UI Integration
The Eclipse platform provides not only the help system, but also support the so-called Context-Sensitive Help (a very confusing name, because the context is only the widget, and not the data). In the following, it is shown, how the connection between the widgets and the help system can be established.
The big picture
The content already defined in the help system can be pointed at from various places in the your application using the so-called help contexts, which on one hand point to the places in the documentation and on the other hand can be assigned to widgets in the application UI.
Establishing contexts
In order to assign the help context to a widget the invocation of the method PlatformUI.getWorkbench().getHelpSystem().setHelp(Control control, String contextId); is used. The contextId is a full-qualified string constructed from the pluginId and the local context name. The context name should be unique for this plug-in (usage of non-unique ids leads to a merge of different subjects, which is a nice feature, but may be not desired). I prefer to create the convenience method for this invocation:
public class HelpUtil
{
public static void setHelp(Control control, String localContextId)
{
if (localContext == null || control == null) return;
PlatformUI.getWorkbench().getHelpSystem().setHelp(control,
Activator.PLUGIN_ID + "." + localContextId);
}
}
There are also methods for registration of other SWT widgets (Control, IAction, Menu, or MenuItem) in the help system, which can be handled by the overloaded version of the method. The invocation of the convenenience method usually looks like: HelpUtil.setHelp(composite, "newWizardPage") and should be invoked from the createControls() of the correponding element. Please note, that the “newWizardPage” is a local name, and the pluginId is added to it inside of the conveninece method. Widgets that do not get focus should not be assigned context ids, since they will never trigger a context-sensitive help
The declarative part
As usual in Eclipse, there is a declarative part, that connects the context ids, set up in the code with the help pages. The connection is established by a special XML file. In order for the platform to know, where to find the file, there is an extension point (org.eclipse.help.contexts), that you need to contribute to:
<extension point="org.eclipse.help.contexts">
<contexts file="contexts.xml" plugin="de.techjava.rcp.ui" />
</extension>
The file attribute specifies the full path to the XML file containing the context definition. The plugin attribute is optional and declares for which plugin the context definition applies. Please note, that if the plugin attribute is ommited, the context names used in the context definition file will be seen as local to the plugin they are declared in. For example, if you want to support the context-sensitive help in plug-in de.techjava.rcp.xyz then your in-code definition of the context should define full qualified context names like de.techjava.rcp.xyz.context1. Either you use the extension point (org.eclipse.help.contexts) in the plugin.xml of the de.techjava.rcp.xyz plugin.xml, or if you put the usage of the extension point into some other plugin (e.G. central for all help), you must provide the plugin attribute with value “de.techjava.rcp.xyz”. This issue is badly discussed in the help guide and is a little confusing. In the context definition file the contexts are defined as follows:
<contexts>
<context id="context1" title="My first context">
<description>This is a test context</description>
<topic href="path/context1.htm" label="Context1"/>
</context>
...
</contexts>
Wizards and Dialogs
Wizards are used with or without dialog.
The call of the Wizard#setHelpAvailable(true) shows the Help button.
The call of the WizardDialog.setHelpAvailable(true); shows the small sexy round Question button.
References
The holiday season is over and we can enjoy an event every week. After
The main message of Egon was the need of formal specification and separation of specification from implementation. He showed how this can help in order to define the semantics. I was glad, that he confirmed some statements I’m discussing in my
Loading ...