Dynamic Context-Sensitive Help

Since 3.1, Eclipse supports dynamic context-sensitive help.

The two pieces of dynamic context-sensitive help include:

An interface class (org.eclipse.help.IContextProvider), and
The Help view (a workbench part)

To provide dynamic context-sensitive help, a UI component must define the associations between its UI controls and help contexts dynamically, by implementing methods of IContextProvider:

getContext(Object target) — returns a help context (ID) for the given target
getContextChangeMask() — returns the mask created by combining supported change triggers, using the bitwise OR operation
getSearchExpression(Object target) — returns a search expression that the help system should use to find more help content related to the current target

The Help view tracks the activation of workbench parts (views and editors), and it checks to see if they adapt to the IContextProvider interface. If they do, the Help view uses the IContextProvider methods (implemented in the UI component) to locate a corresponding IContext object.

The IContextProvider.getContextChangeMask method provides a mask that the Help view uses to determine when a context change occurs dynamically (for example, as a result of a user gesture to change the UI focus).

When the Help view detects a context change, it updates its context-sensitive help presentation to display:

The content of the IContext object that is associated with the current context (that is, the name and description of the UI control, and a list of related help topics)
Dynamic Help search results — a list of help topics found using the search expression that was returned by the IContextProvider.getSearchExpression method

The content of an IContext object (and its association with a particular help context ID) is defined by a context XML file, which is usually contributed by a UA component.

To register IContext content contributions with the help system, a UA plug-in must declare an extension of org.eclipse.help.contexts, identifying both the context XML file and the UI plug-in for which the IContext content is contributed.