15.3. Context-Sensitive Help (F1)

Eclipse provides support for context-sensitive help for widgets, windows, actions, and menus using the F1 key. This help can appear either in a floating "infopop" window or within the dynamic Help view depending on the user's Help preferences. The context-sensitive help that appears can contain a small amount of help for the selected item as well as links to more detailed documentation. For example, opening the Eclipse Hierarchy view and pressing F1 will show context-sensitive help (see Figure 15-14) containing links relevant to the Hierarchy view as well as to views in general.

Figure 15-14. The Hierarchy view showing its associated context-sensitive help in an infopop window on the left and the dynamic Help view on the right.

[View full size image]

To add context-sensitive help to an item, you need to associate a context ID with the item, provide a short description of the item, and create a list of links relevant to the item.

15.3.1. Associating context IDs with items

Whenever a user opens the Favorites view and presses F1, it would be best to have the context-sensitive help appear. First, you need to associate a context ID with the view using the setHelp() method from org.eclipse.ui.help.IWorkbenchHelpSystem.

The context ID is a string with the form <plug-in-id>.<local-context-id>, where <plug-in-id> is the unique plug-in identifier for the plug-in defining the workbench view or editor and <local-context-id> is an identifier unique within that plug-in identifying the context. The <local-context-id> can be composed of any alphanumeric characters and an underscore ("_"), but must not contain any whitespace or periods ("."). In this case, the <plug-in-id> is "com.qualityeclipse.favorites" and you have chosen a <local-context-id> of "favorites_view" for your Favorites view, so the context ID is "com.qualityeclipse.favorites.favorites_view".

Since the Favorites view consists of a single table widget, you will associate the help context ID with the table widget itself. Begin by creating a setHelpContextIDs() method in the FavoritesView class that looks like the following:

// FavoritesView.java
private void setHelpContextIDs() {
   IWorkbenchHelpSystem helpSystem =
      getSite().getWorkbenchWindow().getWorkbench().getHelpSystem();

   helpSystem.setHelp(
      viewer.getControl(),
      "com.qualityeclipse.favorites.favorites_view");
}

The, you can call this method from the existing createPartControl() method in the FavoritesView class.

Help contexts are inherited by child controls. In this case, a help context was assigned to the Favorites viewer control, which has no children. If you were to assign a help context to a composite, then its children will inherit the same help context unless you specifically override it by calling setHelp() on a child control.

The Favorites view also defines several different actions with which you would like to associate help context IDs. Do this by enhancing the setHelpContextIDs() method as follows:

private void setHelpContextIDs() {
   IWorkbenchHelpSystem helpSystem =
      getSite().getWorkbenchWindow().getWorkbench().getHelpSystem();

   // Assign a context ID to the view.
   helpSystem.setHelp(
      viewer.getControl(),
      "com.qualityeclipse.favorites.favorites_view");

   // Assign context IDs to the actions.
   helpSystem.setHelp(copyAction,
      "com.qualityeclipse.favorites.copyAction");
   helpSystem.setHelp(cutAction,
      "com.qualityeclipse.favorites.cutAction");
   helpSystem.setHelp(pasteAction,
      "com.qualityeclipse.favorites.pasteAction");
   helpSystem.setHelp(removeAction,
      "com.qualityeclipse.favorites.removeAction");
   helpSystem.setHelp(renameAction,
      "com.qualityeclipse.favorites.renameAction");
}

Help context IDs can also be assigned to actions defined within the plug-in manifest file by defining a helpContextId attribute. For example, you can enhance the definition of the "Open Favorites View" action like this:

<action
   class="com.qualityeclipse.favorites.actions.
          OpenFavoritesViewActionDelegate"
   icon="icons/sample.gif"
   id="com.qualityeclipse.favorites.openFavoritesView"
   label="Open Favorites View"
   menubarPath="com.qualityeclipse.favorites.workbenchMenu/content"
   style="push"
   toolbarPath="Normal/additions"
   tooltip="Open the favorites view in the current workbench page"
   helpContextId="favorites_view"/>

Note that if local context identifiers are used in the plug-in manifest, then the unique identifier for the declaring plug-in is prepended to make the full context identifier.

15.3.2. IWorkbenchHelpSystem API

The IWorkbenchHelpSystem interface defines a number of useful APIs for assigning help context IDs and programmatically displaying help, such as:

displayContext(IContext context, int x, int y) Displays context-sensitive help for the given context.

displayDynamicHelp() Displays the dynamic entire help for the current UI context.

displayHelp() Displays the entire help bookshelf.

displayHelp(IContext context) Displays context-sensitive help for the given context.

displayHelp(String contextId) Calls the help support system to display the given help context ID.

displayHelpResource(String href) Displays the help content for the help resource with the given uniform resource locator (URL).

displaySearch() Displays the help search system.

hasHelpUI() Returns whether there is a UI help system installed.

isContextHelpDisplayed() Returns whether the context-sensitive help window is currently being displayed.

search(String expression) Starts the search using the help search system.

setHelp(Control control, String contextId) Sets the given help context ID on the given control.

setHelp(IAction action, String contextId) Sets the given help context ID on the given action.

setHelp(MenuItem item, String contextId) Sets the given help context ID on the given menu item.

setHelp(Menu menu, String contextId) Sets the given help context ID on the given menu.

15.3.3. Creating context-sensitive help content

When context IDs have been assigned to views, you need to create the content for each help item, which consists of a description and a set of links. This content is described in one or more context manifest files in XML format. For the items assigned context IDs in the previous section, the contexts.xml file might look like this:

<contexts>
   <context
      id="favorites_view">
      <description>This is the Favorites view.</description>
      <topic href="html/gettingstarted/favorites_view.html"
         label="Using the Favorites View"/>
      <topic href="html/gettingstarted/installation.html"
         label="Installing the Favorites View"/>
      <topic href="html/reference/preferences.html"
         label="Favorites View Preferences"/>
   </context>
   <context id="copyAction">
      <description>
         This command copies a Favorites item from the view.
      </description>
      <topic href="html/gettingstarted/actions.html"
         label="Favorites View Actions"/>
   </context>
   <context id="cutAction">
      <description>
         This command cuts a Favorites item from the view.
      </description>
      <topic href="html/gettingstarted/actions.html"
         label="Favorites View Actions"/>
   </context>
   <context id="pasteAction">
      <description>
         This command pastes a Favorites item to the view.
      </description>
      <topic href="html/gettingstarted/actions.html"
         label="Favorites View Actions"/>
   </context>
   <context id="removeAction">
      <description>
         This command removes a Favorites item.
      </description>
      <topic href="html/gettingstarted/actions.html"
         label="Favorites View Actions"/>
   </context>
   <context id="renameAction">
      <description>
         This command renames a Favorites item.
      </description>
      <topic href="html/gettingstarted/actions.html"
         label="Favorites View Actions"/>
   </context>
</contexts>

Within the contexts.xml file, each context ID is described by its own context element. Each context element has a description element and zero or more topic elements that link to the actual documentation. Each topic element has an href attribute providing the link and a label attribute describing the text of the link, as it will appear in the context-sensitive help.

15.3.4. Context extension point

Now that context IDs have been associated with the view and actions and the context for each help item has been defined, you need to update your plugin.xml file to point to the contexts.xml file and associate it with the main plug-in. The built-in Eclipse wizards make this easy.

Start by opening the plugin.xml file in the help project and switching to the Extensions page (see Figure 15-15). Next, click the Add... button.

Figure 15-15. The Favorites Help manifest file showing the Extensions page.

[View full size image]

When the New Extension wizard opens, select org.eclipse.help.contexts from the list of all available extension points (see Figure 15-16). If you don't see org.eclipse.help.contexts in the list, uncheck the Show only extension points from the required plug-ins checkbox. Click the Finish button to add this extension to the plug-in manifest.

Now, back in the Extensions page of the plug-in manifest editor, right-click on the org.eclipse.help.contexts extension and select New > contexts. This immediately adds a context item to the plug-in manifest. Clicking on this new context item reveals the properties so that they can be modified as follows (see Figure 15-17):

file "contexts.xml"

The name of the context's XML file.

plugin "com.qualityeclipse.favorites"

The text label associated with the perspective.

If you switch to the plugin.xml page of the plug-in manifest editor, you will see the following new section of XML defining the new context file:

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

The plugin attribute is important for associating this context file with the com.qualityeclipse.favorites plug-in. If that is not specified, the context file is associated with the local plug-in in which it is defined.

Note that multiple context files from different plug-ins can be associated with the context ID. This allows one plug-in to extend the context help provided by another.

Now that you have completed the definition of the context-sensitive help, you can test it by opening the Favorites view and pressing F1. The help content for the "favorites_view" context ID should appear in the Help view (see Figure 15-18) or the floating infopop window.

15.3.5. Marker help

The org.eclipse.ui.ide.markerHelp extension point allows plug-ins to associate a help context ID with a particular marker type. Chapter 14, Builders, Markers, and Natures, had one marker type representing two different violations, so you needed to further qualify the help declaration, creating one declaration for each type of violation. The expression <attribute name="violation" value="1"/> indicates that the help context should only be applied to markers having a violation attribute with a value of '1'.

<extension point="org.eclipse.ui.ide.markerHelp">
   <markerHelp
      markerType="com.qualityeclipse.favorites.auditmarker"
      helpContextId="com.qualityeclipse.favorites
         .violationHelp1">
      <attribute name="violation" value="1"/>
   </markerHelp>
   <markerHelp
      markerType="com.qualityeclipse.favorites.auditmarker"
      helpContextId="com.qualityeclipse.favorites
         .violationHelp2">
      <attribute name="violation" value="2"/>
   </markerHelp>
</extension>

The help content for the violation markers is defined as part of the contexts.xml file (see Section 15.3.3, Creating context-sensitive help content, on page 556).