This document is designed to help NetBeans module writers with correctly setting up context-sensitive help for their modules. The document covers the following topics:
The IDE's architecture enables you to:
In order to take advantage of these help features, a NetBeans module writer must be aware of different aspects of the NetBeans help system, specifically:
If your node extends AbstractNode or one of its subclasses, you should implement the getHelpCtx method to return a HelpCtx for the node. The HelpCtx includes the specific Help ID for the help topic for this node. If the node is selected in the explorer and the user hits the F1 key, then the help associated with this node will be displayed.
public class MyNode extends AbstractNode{
public HelpCtx getHelpCtx() {
return new HelpCtx("org.netbeans.modules.xml.tree.nodes.XMLDataNode");
}
}
Wizards are basically a series of Swing Components that are displayed via a WizardDescriptor.Iterator object. The object that the developer creates must implement the WizardDescriptor.Panel interface which includes a method that the developer implements to return the actual Swing Component that is to be displayed (usually a JPanel is returned). Additionally, the developer must implement the getHelp method and return a HelpCtx for this particular wizard step. By default, the Help button is displayed on the resulting JDialog and when the user selects this Help button, the getHelp method is called for the currently displayed WizardDescriptor.Panel object.
Public MyWizardPanel implements WizardDescriptor.Panel{
private JPanel p;
public Component getComponent() {
if(p == null) {
p = new JPanel();
... add Swing Components to JPanel ...
}
return p;
}
public HelpCtx getHelp() {
return new HelpCtx("org.netbeans.modules.xml.core.wizard.DocumentPanel");
}
}
There are two different ways in which you can set help on a NetBeans dialog. If you wish to display a dialog of some sort, you typically create the Swing components you wish to display and then create a DialogDescriptor object which is a NetBeans object that is used to describe the behavior or the dialog. To display help:
public DialogDescriptor(final Object innerPane, final String title,
final boolean modal, final Object[] options,
final Object initialValue, final int optionsAlign,
final HelpCtx helpCtx,
final ActionListener bl)
DialogDescriptor dd = new DialogDescriptor(...);
dd.setHelpCtx(new HelpCtx("dialog_help_id"));
JPanel p = new JPanel();
... add Swing Components to JPanel ...
HelpCtx.setHelpIDString(p, "panel_help_id");
DialogDescriptor DD = new DialogDescriptor(p, "Dialog Title");
When creating a Property Sheet, the developer creates a Sheet.Set object. To populate the Sheet.Set the developer creates and adds a number of Node.Property objects. To display help for the Property Sheet, you must call the setValue method and set the helpID property:
Sheet sheet = Sheet.createDefault();
Sheet.Set ps = sheet.get(Sheet.PROPERTIES);
ps.setValue("helpID", "org.netbeans.modules.xml.tree.nodes.XMLDataNode.Properties");
Property sheets can actually contain multiple tabs, each having their own help associated with them. The method described above to set the help id of a Property Sheet still applies, the only difference is the way in which the additional Property Sheet is created:
Sheet sheet = Sheet.createDefault();
Sheet.Set referenceTab = new Sheet.Set();
referenceTab.setValue("helpID", "org.netbeans.modules.xml.tree.nodes.XMLDataNode.ReferenceProperties");
referenceTab.setName("referenceTab"); // NOI18N
sheet.put (referenceTab);
You can also set an individual help ID for each property (Node.Property) in a property sheet. Presently S1S and NetBeans help is not provided on a per-property basis - help on individual properties is provided in the form of a tooltip.
Some Properties displayed on a Property Sheet require a custom editor. The user accesses the editor by selecting the "..." button on an entry for a specific Property when the user selects that Property. The developer of the custom editor provides a Swing Component (typically a JPanel) which is ultimately displayed in a JDialog. If Help is to be supplied on the resulting JDialog, then the help ID string of the supplied Swing Component must be set.
Public MyPropertyEditor extends PropertyEditorSupport{
public Component TreeNodeFilterCustomEditor() {
JPanel p = new JPanel();
... add Swing Components to JPanel ...
HelpCtx.setHelpIDString(p, "org.netbeans.modules.xml.tax.beans.editor.TreeNodeFilterCustomEditor");
return p;
}
}
Some Custom Property Editors display a number of tabs. Depending on the tab that is displayed, different Help may need to be displayed. In this case, you should set the help ID on the property editor's JTabbedPane. If you want the help ID to change when the user switches tabs, then you should listen for changes in the selected tab, and change the ID on the JTabbedPane each time.
For NetBeans 3.4 and earlier, you can set help IDs on tabs as shown in this example:
class MyTabPane extends JTabbedPane implements ChangeListener {
private HelpCtx[] helps = new HelpCtx[3];
public MyTabPane() {
add(new Panel1());
helps[0] = new HelpCtx("help_1");
// etc.
stateChanged(null);
}
public void stateChanged(ChangeEvent ignore) {
HelpCtx.setHelpIDString(this, helps[getSelectedIndex()]);
}
}
In NetBeans releases later than 3.4, you can use the HelpCtx.Provider to simplify the process, as shown in the following example:
class MyTabPane extends JTabbedPane implements HelpCtx.Provider{
private HelpCtx[] helps = new HelpCtx[3];
public MyTabPane() {
add(new Panel1());
helps[0] = new HelpCtx("help_1");
// etc.
}
public HelpCtx getHelpCtx() {
return helps[getSelectedIndex()];
}
}
Many modules define their own Service Types such as Ant Compilation. Additionally, many define their own System Options such as the UDDI Registries. In both cases, developers extend either the ServiceType or the SystemOption abstract class. Defined in each class is the getHelpCtx method. If you wish to display help for your Service Type or System Option, implement the method:
public class AntCompilerType extends CompilerType{
public HelpCtx getHelpCtx() {
return new HelpCtx ("org.apache.tools.ant.module.run.AntCompilerType");
}
}
Note that the CompilerType class extends the ServiceType class.
There are two lines you need to add to your module's manifest file in order for your help set to be used at runtime:
A module's help set must be defined in the JavaHelp Folder and this is specified in its Layer file. Layer files are typically called mf-layer.xml, layer.xml, or modulemf-layer.xml, layer.xml, or *Layer.xmlLayer.xml. You can find the name of your module's layer file in the module JAR's manifest. The following was taken from the HTTP Monitor Module mf-layer.xml file:
<filesystem>
<folder name="Menu">
<folder name="Help">
<folder name="HelpShortcuts">
<!-- Insert help set under the separator line below the Usersguide help -->
<attr name="org-netbeans-modules-usersguide-sep.instance/org-netbeans-modules-web-monitor-mainpage.xml" boolvalue="true"/>
<!-- Insert help set under JSP/Servlet Help -->
<attr name="org-netbeans-modules-web-ie-mainpage.xml/org-netbeans-modules-web-monitor-mainpage.xml" boolvalue="true"/>
<file name="org-netbeans-modules-web-monitor-mainpage.xml" url="help-main-ref.xml">
<attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.web.monitor.Bundle"/>
<attr name="SystemFileSystem.icon" urlvalue="nbresloc:/org/netbeans/modules/web/monitor/resources/blank.gif"/>
</file>
<!-- Insert help set above the separator line separating 3rd party help -->
<attr name="org-netbeans-modules-web-monitor-mainpage.xml/org-netbeans-modules-usersguide-second-sep.instance" boolvalue="true"/>
</folder>
</folder>
</folder>
<folder name="Actions">
<folder name="Help">
<file name="org-netbeans-modules-web-monitor-mainpage.xml" url="help-main-ref.xml">
<attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.web.monitor.Bundle"/>
<attr name="SystemFileSystem.icon" urlvalue="nbresloc:/org/netbeans/modules/web/monitor/client/icons/menuitem.gif"/>
</file>
</folder>
</folder>
<folder name="Services">
<folder name="JavaHelp">
<!-- Merge after Core IDE Help: -->
<attr name="org-netbeans-modules-usersguide-above-regular.txt/org-netbeans-modules-web-monitor-resources-helpset.xml" boolvalue="true"/>
<!-- Merge after JSP/Servlet Help: -->
<attr name="org-netbeans-modules-web-ie-helpset.xml/org-netbeans-modules-web-monitor-resources-helpset.xml" boolvalue="true"/>
<file name="org-netbeans-modules-web-monitor-resources-helpset.xml" url="helpset-decl.xml"/>
<!-- Merge before 3rd party help: -->
<attr name="org-netbeans-modules-web-monitor-resources-helpset.xml/org-netbeans-modules-usersguide-below-regular.txt" boolvalue="true"/>
</folder>
</folder>
</filesystem>
Menu Folder - Use the Menu folder to place the shortcut to the help set in the IDE's Help | Help Sets menu. Notice that in standard NetBeans releases this submenu contains two separators. One is below the Core IDE Help shortcut, the other is above all third-party help sets like the Ant manual. (If you do not have the Ant Documentation module installed, this second separator doesn't appear. Sun One Studio or third-party releases may have additional separators between the Core IDE Help and 3rd party help.)
The shortcuts to all module help sets should appear between these two separators. Thus the layer file should always specify the following:
<!-- Insert help set under the separator line below the Usersguide help -->
<attr name="org-netbeans-modules-usersguide-sep.instance/org-netbeans-modules-web-monitor-mainpage.xml" boolvalue="true"/>
<!-- Set the location of the help set by specifying which help set it should follow -->
<attr name="org-netbeans-modules-web-ie-mainpage.xml/org-netbeans-modules-web-monitor-mainpage.xml" boolvalue="true"/>
<!-- Insert help set above the separator line separating 3rd party help -->
<attr name="org-netbeans-modules-web-monitor-mainpage.xml/org-netbeans-modules-usersguide-second-sep.instance" boolvalue="true"/>
The Menu folder also lets you set the icon that precedes the shortcut in the Help menu. The Core IDE Help should be the only help set that has an icon. Every other help set should be preceded by a blank 16x16 pixels icons, like so:
<attr name="SystemFileSystem.icon" urlvalue="nbresloc:/org/netbeans/modules/web/monitor/resources/blank.gif"/>
Actions Folder - Provides the general action that opens the HTTP Monitor help set in the IDE's help viewer. By default this action displays in the Help | Help Sets menu, but it can also be configured in Tools | Options.
Services Folder - Use the Services folder to merge the help set into the IDE's JavaHelp viewer. This folder also specifies the order in which the help sets appear in the table of contents and index. As with the shortcuts in the Help menu, all module help sets should be located between the Core IDE Help and third party help. You can specify this by with the following:
<!-- Merge after Core IDE Help: -->
<attr name="org-netbeans-modules-usersguide-above-regular.txt/org-netbeans-modules-web-monitor-resources-helpset.xml" boolvalue="true"/>
<!-- Set the location of the help set by specifying which help set it should follow: -->
<attr name="org-netbeans-modules-web-ie-helpset.xml/org-netbeans-modules-web-monitor-resources-helpset.xml" boolvalue="true"/>
<!-- Merge before 3rd party help: -->
<attr name="org-netbeans-modules-web-monitor-resources-helpset.xml/org-netbeans-modules-usersguide-below-regular.txt" boolvalue="true"/>
If you have any questions about this, please send e-mail to Paul Fussell as he is the one who added this to the various Layer files and understands it.
Typically, the Help files are added under a javahelp subdirectory off of the module root directory. Like source code, all JavaHelp documentation must be placed into a globally unique package to avoid conflicts. If two modules put help files into the same package, it will result in broken links. Therefore, the javahelp subdirectories should mirror the package structure of the src directory where the java source is located. While this is not a hard requirement and Help files can be put anywhere, this is the best way to avoid conflicts between module help sets.
For example, the structure of the module source and documentation of the EJB module in SunTM ONE Studio 4, Enterprise Edition for JavaTM is as follows:
ejb (module root directory)
|
src/com/sun/forte4j/j2ee/ejb/ (several subdirectories of source files)
|
javahelp/com/sun/forte4j/j2ee/ejb/docs/ (several subdirectories of documentation files)
Wherever you choose to place your documentation files, your build.xml
file must correctly that specify where the Help files are located so that the
module build process can find them and build the help set.
<target name="netbeans" depends="jars,javahelp">
<genlist targetname="nbm" outputfiledir="netbeans"/>
</target>
<target name="javahelp">
<mkdir dir="javahelp/com/sun/forte4j/j2ee/ejb/docs/JavaHelpSearch2"/>
<jhindexer basedir="javahelp/com/sun/forte4j/j2ee/ejb/docs/"
db="javahelp/com/sun/forte4j/j2ee/ejb/docs/JavaHelpSearch2"
jhall="${nbroot}/nbbuild/external/jhall-1.1.2_02.jar">
<include name="**/*.html"/>
<include name="**/*.htm"/>
<exclude name="JavaHelpSearch2/"/>
<exclude name="ja/"/>
<exclude name="credits.html"/>
</jhindexer>
<mkdir dir="javahelp/com/sun/forte4j/j2ee/ejb/docs/ja/JavaHelpSearch2"/>
<jhindexer basedir="javahelp/com/sun/forte4j/j2ee/ejb/docs/"
dB="javahelp/com/sun/forte4j/j2ee/ejb/docs/ja/JavaHelpSearch2"
locale="ja"
jhall="${nbroot}/nbbuild/external/jhall-1.1.2_02.jar">
<include name="ja/**/*.html"/>
<include name="ja/**/*.htm"/>
<exclude name="ja/JavaHelpSearch2/"/>
<exclude name="ja/credits.html"/>
</jhindexer>
<mkdir dir="netbeans/modules/docs"/>
<locjar jarfile="netbeans/modules/docs/ejb.jar"
compress="true">
<fileset dir="javahelp" excludesfile="${nbroot}/nbbuild/standard-jar-excludes.txt"/>
<locale name="ja"/>
</locjar>
</target>
The path to the javahelp sources above follows the standard NetBeans pattern of matching documentation package hierarchies to source package heirarchies as described above. If you want to use a different directory structure, you must alter the entries in the javahelp target to correctly locate the directory where the files are located.
Note: The details of how build scripts work may vary from release to release. You should always compare against existing scripts in case of problems.
It is therefore necessary for all Help IDs to be unique. The best way to
avoid collisions to preface all Help IDs with the standard package name
of the module it comes from. Thus for the Execution tabs of the property
sheet for a form object node, you should set the Help ID to org.netbeans.modules.form.FormDataObject.ExecutionTabproperties
Questions or Comments? Send me email.