NetBeans JavaHelp Integration API - NetBeans API Javadoc 5.5.0

Overview

NetBeans JavaHelp Integration API

It is possible to add JavaHelp and context help capabilities to modules. This API module makes that possible. It also includes the JavaHelp standard extension library itself.

JavaHelp installation

Helpset registration

You can add JavaHelp via your XML layer. First you need to add the helpset to the IDE. This has several effects: it ensures that context help can use your helpset; it enabled help links to use help IDs defined in this helpset; and assuming the helpset is marked to be merged into the master helpset, this means that the menu item Help | Contents will show any navigators you define in your helpset, merged into others.

To add a helpset, you must register an object implementing javax.swing.HelpSet into the IDE's lookup system. The normal way to do this is to create an XML file with a special DTD which you place into the Services/JavaHelp/ folder of the system filesystem via layer. This file specifies the URL to the help set, for example:

<?xml?>
<!DOCTYPE helpsetref PUBLIC
          "-//NetBeans//DTD JavaHelp Help Set Reference 1.0//EN"
          "http://www.netbeans.org/dtds/helpsetref-1_0.dtd">
<helpsetref url="nbresloc:/org/netbeans/modules/foo/help/HelpSet.hs"/>

By default such a helpset will be merged into the IDE's master help navigators. You may opt out of this by specifying merge="false" on the <helpsetref/>. If providing a custom help set instance via lookup, in order to turn off merging you should set the "key data" on the helpset with the context OpenIDE and key mergeIntoMaster to Boolean.FALSE.

Using nbresloc implies that the helpset can be found in the module's classloader, for example in its main JAR or in an extension ZIP or JAR referenced via the Class-Path manifest attribute. There is a URL protocol nbdocs which is similar to nbresloc and will load anything it can. It also will try to load localized resources using InstalledFileLocator with a prefix of docs/. Given the current implementation of the NetBeans installation structure, this will permit the help set and associated files to reside in a package hierarchy underneath the docs/ folder (of the IDE installation or user directory), if not in the module classloader.

Shortcut registration

To add a shortcut to a specific help ID in your help set, there is a different XML DTD you can use. The shortcut XML specifies the help ID to display (which must be present in some registered help set of course), for example:

<?xml?>
<!DOCTYPE helpctx PUBLIC
          "-//NetBeans//DTD Help Context 1.0//EN"
          "http://www.netbeans.org/dtds/helpcontext-1_0.dtd">
<helpctx id="org.netbeans.modules.foo.some-topic"/>

By default such a link will display a help window containing navigators only for the help set from which it was taken. If you prefer to display navigators for all merged help sets, specify showmaster="true" on the <helpctx/>.

This XML file's only use is that it has a menu/toolbar presenter which opens the specified help page. (You can customize its display name and icon using the normal means available to templates etc.) You could provide an alternate means of displaying help shortcuts, however the functionality of showing the master navigators is only accessible via the presenters of this kind of XML file.

Note that usage of help shortcuts is no longer recommended by NetBeans style guidelines.

Module dependency

Note that JavaHelp capability is not automatically guaranteed to modules. Rather, modules supplying JavaHelp documentation which wish to ensure that this documentation will be visible, must declare an explicit dependency on the JavaHelp library. This library provides the capability org.netbeans.api.javahelp.Help, so a module may declare the dependency as follows:

OpenIDE-Module-Requires: org.netbeans.api.javahelp.Help

Context Help

When the help set is specified in the module, this permits the IDE to associate context help with various features associated with the module (or, technically, other modules - if you know their help IDs and they do not themselves bind them). There are several ways to associate help IDs with module features so that they may be used by the IDE, mostly revolving around the API class HelpCtx.

This class has several constructors for different purposes; the constructor which takes a Class is convenient for some purposes, or the one taking a String is also fine. The constructor with a string directly uses that help ID, which may be any string uniquely identifying the feature, and associated with an HTML page using the map file; when passing in a class object, this should typically be the class returning the help object, and the ID will be the fully-qualified class name, which avoids the need to separately choose a good help ID.

public HelpCtx getHelpCtx() {
    return new HelpCtx(ThisAction.class);
}

<mapID target="com.mycom.mymodule.ThisAction" url="this-action.html"/>

There are a number of different points in the APIs where you may specify a HelpCtx in this fashion:

• Node.getHelpCtx()
• DataObject.getHelpCtx()
• TopComponent.getHelpCtx()
• SystemAction.getHelpCtx()
• NewType.getHelpCtx()
• PasteType.getHelpCtx()
• DialogDescriptor.getHelpCtx()
• WizardDescriptor.Panel.getHelpCtx()
• SystemOption.getHelpCtx()
• ServiceType.getHelpCtx() (applies equally to executors and compiler types)

• On any (Swing lightweight) component you use in a GUI, by means of HelpCtx.setHelpIDString(...). This is especially useful for custom property editor components.
• On any JavaBean, by adding the help ID as a (string) value to the (FeatureDescriptor) attribute named helpID in a BeanDescriptor, as described by the JavaHelp specification in regards to beans. This will be interpreted by any bean container (e.g. InstanceDataObject or BeanNode or *.ser files) that uses InstanceSupport.findHelp(...).

  This technique may also be used to add context help support to the editor kits used in the Editor API; create the bean info for the subclass of EditorKit, and this help will be used for the editor pane.

  As of NetBeans 3.4, you may also use the attributes propertiesHelpID and expertHelpID on the BeanDescriptor in order to specifically supply help for regular (resp. expert) property sets only. To provide a specific help for just one property, use helpID on the PropertyDescriptor.

• As the helpID value of a Node.PropertySet or Node.Property.
• For services on the system filesystem (typically installed via layer) and the folders they are in (typically beneath Services/), you may use the file attribute helpID to specify the help ID right in the layer. See the Services API for details.
• In the <homeID> tag of a help set file; in this case, the specified help ID is understood as applying generally to the module. Typically it should be some sort of index page.
• In various navigational views used by JavaHelp, such as the table of contents or the index.

The proper help page for the selected component, if there is one, is displayed by the IDE by default using F1. This applies to various visual components (when they have focus), the current TopComponent, and nodes (or the objects they represent) when the node is selected in an Explorer window (or custom windows using ExplorerUtils). Programmatically, you may also display help by using the JavaHelp module API:

String id = ...;
Help help = (Help)Lookup.getDefault().lookup(Help.class);
if (help != null && help.isValidID(id, true).booleanValue()) {
    help.showHelp(new HelpCtx(id));
} else {
    Toolkit.getDefaultToolkit().beep();
}

If you are having trouble figuring out why you are not seeing the help you expect, try running the IDE with the command-line option -J-Dorg.netbeans.modules.javahelp=0 and look in your system/ide.log file for details. -J-Dorg.openide.util.HelpCtx=0 may also be used to get further information on association between help IDs and GUI components, and so on.

External links in JavaHelp

<object CLASSID="java:org.netbeans.module.javahelp.BrowserDisplayer">
    <param name="content" value="http://www.netbeans.org">
    <param name="text" value="Click here">
    <param name="textFontFamily" value="SansSerif">
    <param name="textFontSize" value="x-large">
    <param name="textFontWeight" value="plain">
    <param name="textFontStyle" value="italic">
    <param name="textColor" value="red">
</object>

<object CLASSID="java:org.netbeans.modules.javahelp.BrowserDisplayer">
    <param name="content" value="http://java.sun.com/downloads/ea/index.html">
    <param name="text" value="<html><u>Early Access</u></html>">
    <param name="textFontSize" value="medium">
    <param name="textColor" value="blue">
</object>

Extension of nbdocs protocol

nbdocs:/org/nb/mod/foo/docs/somepage.html

nbdocs://org.nb.mod.bar/org/nb/mod/foo/docs/somepage.html

<a href="nbdocs:/org/netbeans/modules/web/monitor/docs/monitor/ctx_monitorintro.html">
Monitoring Data Flow on the Web Server</a>

<a href="nbdocs://org.netbeans.modules.web.monitor/org/netbeans/modules/web/monitor/docs/monitor/ctx_monitorintro.html">
Monitoring Data Flow on the Web Server</a>