Adding context sensitive help

The Eclipse platform provides means of showing little a help popup window when the user presses the button F1. These so called Infopops contain short help texts and optional hyperlinks to get more information in the main help window.

These infopops can be added to any SWT control so that a pressed key F1 triggers their display. The task for a developer is to create the context entries for the infopops and connect them to the controls that should be enabled to show them on demand. Using the Help Exporer view can simplify collecting the information needed to build the infopops. In the next sections depict the creation and addition of such an infopop. The used infopop describes the purpose of a view and adds two hyperlinks to both a help file in the same plug-in and one in another standard plug-in.

Adding the plug-in extension

The extension is best added in the Plug-in Manifest Editor that is opened by default when double-clicking on a plug-in manifest file plugin.xml
Make sure that the plug-in org.eclipse.help defining the extension-point contexts is listed in the Dependencies page
Add an extension to the plug-in basing on the extension-point org.eclipse.help.contexts using the Add... button in the Extensions page
In the Extension Wizard Selection page of the New Extension wizard select Generic Wizards and Schema-based Extension and proceed to the next page
Page Extension Point Selection allows you to select org.eclipse.help.contexts and press Finish
The newly added extension point has to be further defined adding configuration elements. Right-click on the extension point and chose New | contexts in the context menu

Adding the file contents

Select the new context element, right-click on it and select the context menu item Properties. In the Properties view enter a valid file name like contexts.xml as value for the file property.

Open the file above (contexts.xml) in an editor and add the following lines to create a new context identified by MyViewContextID:

<contexts>
	<context id="MyViewContextID">
		<description>My view shows nice stuff. </description>
		<topic label="My view" href="doc/my_view.htm"/>
	</context>
</contexts>

Create a directory doc if it does not exist yet and add a file my_view.htm in there

Open this new file doc/my_view.htm in an editor and create some HTML contents like:

<html>
	<head>
		<title>My view</title>
	</head>
	<body>
		<h2>My view</h2>
		<p>
			My view shows nice stuff.
		</p>
	</body>
</html>

Adding the external references

Since our view is an extension to the platform views a reference to the default view help texts is desirable to give the user more information on how to use views in general. There are already help pages describing views in general but how to identify them and how to refer to them? When looking at infopops of standard platform views, they all have a hyperlink labeled Views. The easiest way of identifying such an existing context entry is by opening the Help Exporer view and using its Search command with the search text Views on the selected root node Extensions - Contexts

After clicking the Search button for a couple of times you will hit a context entry like the one shown in the figure above for the Properties view. You can now use the values of the properties Hyperlink reference and Label and create a similar entry in your context definition:
```
<contexts>
	<context id="MyViewContextID">
		<description>My view shows nice stuff. </description>
		<topic label="Views" href="../org.eclipse.platform.doc.user/concepts/concepts-5.htm"/>
		<topic label="My view" href="doc/my_view.htm"/>
	</context>
</contexts>
```
Please note that references to help files in other plug-ins always have to be relative. That is, they must start with the ../ parent path directive.

Adding the context-code to the view

Considering that there already exists a view in your plug-in, you can open its source code in the Java editor
Add the new method to set the help context for a given SWT coltrol:
```
    private void setHelp(Control control) {
        WorkbenchHelp.setHelp(control,
            "myplugin.MyViewContextID");
    }
```
Please compose the fully qualified context identifier from the plug-in unique identifier and the context identifier separated by a dor (.). In our example it was composed from a plug-n identifier myplugin and a context identifier MyViewContextID.
Add the new setter method calling line at the beginning of the method to create the client control of the view:
```
public void createPartControl(Composite parent) {
        setHelp(parent);
```
The context is best linked to the parent control to ensure that regardles which control within the view has the focus, the infopop can be identified and displayed.

Infopops
Simple plug-in example
Navigating the help system
Adding to the table of contents

Help Exporer view
Properties view
Plug-in manifest editor
Dependencies page
Extensions page
Plug-in Manifest
Extension-point org.eclipse.help.contexts